Writing Code: an Art Form
A senior software full-stack developer joined the team 2 weeks ago. Ten years of experience, and he probably wasn’t too stoked a 6-month junior developer was walking him through our code base. Me. That junior was me. We had designed a product together for a live-feeder, and I gave him some starter jobs on writing the skeleton API for the object as well that would combine existing API objects to create the properties of that object. On designing the API, I remember that a proposed solution included having to generate feeds with at least O(N²) time. I was not willing to accept such a solution, given the complexity of the project and the amount of data involved— this proposed solution did not include any caveat on risking memory optimization. My reaction likely created a further rift between the power-dynamics of career-seniority and work-status.
When I came back to check on the initial groundwork for the backend, I raised concern with the naming conventions and choices for objects in properties. Despite our collaborative design, what I saw gave me the impression either:
- There was perhaps some kind of misunderstanding of how those properties organize the object itself
- The code was entirely unclear on the organization itself
I explained giving proper names for properties will prevent confusion later on. After walking through what the backend should look like, I moved him to the front-end to continue the crash-course on our code base. I sat next to him to help write a module, stopping occasionally to comment on syntax and encourage consistent documentation. He laughed. “You like to write pretty code.” For a second, I was kind of taken aback.
Like reading a resume, the goal of writing code is that someone else should be able to take a quick glance and get a good understanding of what it does. In school, I was forced to write Javadocs with utmost strictness. Each mistake made was 5pts taken off my assignment per method. Since then, my feelings on documentation have changed quite a bit. Documentation should not be so heavy that it’s just repetition of what you can read in the the code itself, but it should simply explain the “whys” and “hows”. Code should always strive to be as concise as possible, but not at the cost of sacrificing memory-usage optimization (to be continued in a following article on AOP).
I once handed my professor a resume for feedback for an upcoming conference I was applying to for scholarship. “This is too wordy,” he said after a 30-second glance. “People reading will think you write code just like the way you wrote this resume.”
After swallowing hurt pride, I decided wanted to better myself: I realized everything and I write reflects on me as a coder — chances are, I perform the same behavior in my code. This is something I actively work on and continue to strive for improvement.
Difficulty reading code can come from more than just poor documentation. Say someone decides to write a program using single characters `a`, `j`, `s` for variable and function convention, or simply names misnomers.
Saving lines and space in code is important, but not being clear on what is being manipulated can come at the price of causing confusion later to other programmers that want to dive into your program. Writing code should contain naming conventions that is not only readable, but are also easily interpreted by other coders who may look at your project in the future.
If you have difficulty reading someone else’s code, even over something minor as documentation, that difficulty reveals the writer’s lack of attention and diligence, which can even bleed over to the code itself. I’m not at all implying that the senior coder has these attributes, but I am saying that being careless in what you write might also indicate a similar attitude in problem solving.
Writing code is ultimately, an art form. There are general recommended conventions and syntax appropriate for certain use cases, but when it comes to object and infrastructure design, it seems like we see broad differences in writing styles that have potential for obfuscating flow (for a compiler) and readability (for the developers).
Despite any possible constraints of writing code (whether it be by language capability or personal experience), it is safe to agree on general, compatible goals for writing programs:
Write programs that are easy to maintain, read, and debug
Code that’s easy to read but not memory-usage optimal can result in excessive memory references and frequent storage allocation which can lead to missed caches, page faults, and terrible performance.
Write programs that efficiently utilizes memory
Code that optimizes memory usage but doesn’t achieve the first goal can be considered “spaghetti code”.
Stay tuned for a follow-up on a continuation of this topic: object-oriented programming’s attempt for achieving these goals through Aspect-Oriented Programming (AOP).
