re: What are the least intuitive fundamentals and best practices in software development? VIEW POST


Non-intuitive: There's generally no correlation between amount of code and usefulness to a user. There is however a definite correlation between amount of code and amount of defects.

This leads to the best practice of keeping code as small as possible, primarily through reduced redundancy.

Non-intuitive: Comments are the least effective way to describe what code is doing. They end up diverging from the code over time, and may miss nuances. Comments can actually make code harder to read.

Code is the best way to describe code. Using effective names and clear structures is far better than comments.


Regarding your first point, I'm reminded of Jack Diederich's talk "Stop Writing Classes" where he says: we don't ship code, we ship features.

He also says "I hate code and I want as little of it as possible in our product" :)


I'm sure he'd appreciate that my book What is Programming? starts out by looking at users and understanding features, not even getting to code until about half way through. :)

Yes, we have to learn that code is a tool, it is not the product.


Comments should never be used to describe what code is doing. It should describe why it's being done the way it is. You've got the code right in front of you, but if it isn't immediately obvious what it's doing, a comment explaining the why is quite nice. Note that these comments rarely go at the declaration site of a method, they're more effective when they're written inline, as close to its relevant code as possible.

And on the other extreme, don't go so deep into the why comments that the code becomes difficult to read. The code is still the shining star, make sure it is still easy to find the code amongst your comments. Anything longer should go in the official documentation.


Reminds me of a quote (reformatted):

Goal of programmers is to ship, on time, on budget. It’s not “to produce code.”

IMO most modern C++ proponents:
1) overassign importance to source code, over
2) compile times, debugability, cognitive load for new concepts and extra complexity, project needs, et cetera

2 is what matters.

~ Christer Ericson


Isn't the importance of the code what helps ensure all that stuff under 2?

code of conduct - report abuse