Isaac Taylor has written an article that we’ve all probably read before: the dos and don’ts of programming style.
Striving to write good code should be the goal of every Software Developer. Writing code that is easily maintainable, robust, simple, and makes sense is no easy task. It takes years of practice and uncountable hours of time to become a good Programmer, and the job is never really done.
Some of his advice is pretty standard (e.g. choose meaningful variable names) but this one ruffled my feathers a bit: “Comment frequently”. If the article’s comments are any indication, others feel the same way. A comment from reader MarchVeg sums it up:
Personally I don’t agree with comments, they are another thing to maintain as the code changes over the years.
I find that comments tend to be the most brittle part of source code. I would change Isaac’s recommendations for comments to:
-
Comment independent units of code such as classes and functions as a form of documentation and a reminder to maintainers. These comments are more likely to be relevant over time since function maintainers are free to change how they implement a certain task but shouldn’t change a function so it does something entirely different than calling code expects.
-
If you find yourself needing to comment particularly complicated lines of code try rewriting it first. This is where tests can be very helpful. It’s alright if the code increases in size as long as it becomes more clear and simple.
I suppose my second point also goes against Isaac’s recommendation that you shouldn’t “write 4 lines of code when 2 will do”, which I also disagree with. 4 lines of simple idiomatic code always beat 2 lines of terse obfuscated code. I’m sure what Isaac meant to say was “don’t write overly verbose code when succinct code will do.”
Update: As it turns out, the actually author of the article above isn’t Ilias Tsagklis, it’s Isaac Taylor. Sorry about that Isaac!