2025 Public Training Schedule
January 14 – 17, 2025 – Agile Analysis and Design Patterns – Half-Day Sessions
Follow me on Twitter:
Blog Post Categories
- Announcements {19}
- Articles {2}
- Bits and Pieces {74}
- Blogosphere {1}
- Bonuses {2}
- Build in Small Batches {27}
- Collaborate {38}
- Create CLEAN Code {34}
- Implement the Design Last {11}
- Integrate Continuously {30}
- Off-Topic but Interesting {3}
- Rants {82}
- Refactor Legacy Code {24}
- Say What, Why, and for Whom Before How {22}
- Seven Strategies {38}
- Specify Behaviors with Tests {17}
- Write the Test First {27}
Archives
Privacy Policy
(c) 2024 To Be Agile
- September 21, 2016
- Bits and Pieces
I have been accused in the past of encouraging developers to write uncommented code and this is true, but not because I don’t care about maintainability. On the contrary, I care about maintainability a great deal and that’s exactly why I encourage developers to think twice before they write a comment in their code.
Commenting code sounds like a good idea but it can encourage poor programming habits. Developers are less inclined to use meaningful names for behaviors or make their code expressive because it’s explained in the comments. But comments are not code and comments and the code they’re describing can easily get out of sync with each other. And efforts to keep them in sync are actually quite expensive, so commenting code can quickly become a liability. We want to be careful not to assume this additional cost unless it’s absolutely necessary.
The software itself is by far the best medium to express what it’s doing. We should strive to write software that’s clear and understandable because software needs to be maintained.
In scriptwriting, it’s often considered a sad device to use a narrator to explain a scene. Exposition is boring and it’s the sign of poor storytelling. The same is true in code. Our primary focus as software developers should be communicating in our code. We want to communicate what our design is while hiding as much as possible as to how that design is implemented. We want our code to be encapsulated with strong contracts so they are straightforward to understand and maintain.
There is an art and a science to this but unfortunately I don’t often see it taught in school. Some of my clients have me train all their developers, including their new hires who are fresh from school. New hires in my classes often laugh when they hear my comments on comments because oftentimes their professors have drilled into them that they should have a comment for every line of code and that you should always explain what you’re doing in a comment.
This is not considered an industry best practice. Maybe these practices work when you’re building a simple software project like the kind you do within a semester in college, but not when you’re building enterprise software. Large projects require discipline and they also require a certain level of knowledge from the people who are writing and maintaining the code.
I expect the people who read my code in the future will understand the basics of software development. I shouldn’t have to explain what my code is doing. If I felt I had to then I should rewrite my code so it’s easier to understand. Of course, there have been times that I had to break this rule due to other considerations such as performance, availability, security… but other considerations aside, I try to avoid comments and I discourage other developers from adding comments that explain what their code does.
However, there is a class of comments that are important to include in code and I’ll discuss those comments in next week’s post.
Previous Post: « The Heartbeat of a Project
Next Post: More Comments on Code Comments »