Code Comments
Phil Eaton on his personal blog:
Over time with the help of books like Clean Code, I grew disdainful of comments. Good code should be self-documenting. Whenever I needed to write a comment to explain something, I’d realize I could easily rename some key variable or function. I grew more comfortable with variables and functions with a few words in the title. Better to spend time on good code structure and naming.
He goes on to explain how is view has fundamentally changed with experience.
Every time I have to call out a line of code in a pull request, that’s immediate cause for that code to be modified with comments.
In every freaking project I have ever worked on, we have had discussions about code comments. Most developers flat out refuse to add meaningful information that is not strictly programming code to a project unless forced to do so until penalty of termination. No amount of persuading or explaining could sway the comment-refusers.
Especially when you’re new to a project and are confronted with an avalanche of code, sensible comments help tremendously in understanding the reasoning of why certain code was written in a certain way. It helps mapping out the code base, to understand why a file exists and what it does. All without having to keep the entire application structure in your head. The larger a project gets, the more this creates massive overhead to tackle even single problems. I have experienced first-hand an extreme situation where this overhead resulted in an eight-hour work day where my only contribution to the project was to add a missing space in an online shop checkout cart. At the time, I was working with the team for ten weeks. Most questions regarding older components couldn’t be answered because no one remembered why they did it in the first place. I quit after that, as it was a measure of even more fundamental issues the project had.
Comments should rarely, if ever, attempt to explain logic that is plain to see in code. But when you have hundreds of files and a nested structure ten levels deep with abstractions right, left, top, bottom and at the z-axis, comments detailing the relationship of files are extremely helpful. So are comments explaining what a complicated non-obvious function call does, why it does it and why it was implemented this way.
One could argue that the code base should be overhauled completely if this becomes necessary. But as everyone who has ever worked on an enterprise-level project and used any kind of frontend JavaScript framework with it, knows: it will get messy. The customers’ mindset is that they pay for features and not for refactoring.
All the more important to document and comment the code thoroughly so it gets easier to pull things apart without breaking the whole application. You’re writing the comments for your future self as well. You will forget what today appears obvious to you.