Code Comments – Comment Everything vs Write More Readable Code

commentsjavascript

When trying to learn about proper comment practices, I found a lot of conflicting opinions, and it's obviously a very subjective topic. So I'm not going to ask "Should I comment, or should I not?"

The question I'd like to pose is, for me, as a self taught developer interested in applying for programming jobs in the future, a vital one: Of the two strategies

"Comment the right code in the right way." – (comments where needed)

and

"Instead of writing comments, write more readable code." – (if you need comments, your code is bad)

are both valid strategies in programming?

If I submit an application with code samples including masterfully written code and no comments, are experienced programmers likely to be familiar with that approach?

I'm not asking "Will the specific guy reading my application like my coding style", obviously no one can guess that, I'm just looking for a general answer as to whether both practices are common, or if my code will be seen as terrible across the board.

Best Answer

Your question implies a dichotomy that doesn't exist.

Should you write cleaner code, if doing so will make it clear enough where you don't have to document it? Absolutely.

Should you write comments and otherwise provide documentation, when it will improve the clarity and understanding of the code? Of course.

Why are these two things not mutually exclusive?

  1. Some of the code that you write will favor better performance over high readability.
  2. Architecture is not self-documenting. While code in isolation is generally fairly easy to understand if it's written cleanly, the architecture surrounding it is not always.
  3. Design decisions are not always self-evident.
  4. What business process or problem the code solves is not always self-evident.

In short, you can't write non-trivial code in such a way that it is always completely self-describing. Part of your job is to insure that the fellow coming after you doesn't require a year to figure out your code, and for that, good documentation is a necessity.

Related Topic