Best practices for writing code comments - Deepstash

Best practices for writing code comments

stackoverflow.blog

STASHED IN:

0 Comments

All programs should be commented in such a manner as to easily describe (in English) the purpose of the code and any algorithms used to accomplish the purpose. A developer should be able to utilize...

2

STASHED IN:

9

"Programs must be written for people to read and only incidentally for machines to execute."

3

STASHED IN:

9

Your comments should be D.R.Y. The acronym stands for the programming maxim “Don’t Repeat Yourself.” This means that your code should have little to no redundancy. You don’t need to comment a piece...

1

STASHED IN:

10

A misuse of comments is to provide information that should have been in the code. An example is when someone names variables badly and then tries to add comments describing them:

# A di...

1

STASHED IN:

9

The most infamous comment in the Unix source code is “You are not expected to understand this,” which appeared before some hairy context-switching code. It turned out that Dennis Ritchie and co-aut...

1

STASHED IN:

9

It’s a good idea to comment code that someone else might consider unneeded or redundant, such as this code:

final Object value = (new JSONTokener(jsonString)).nextValue();

1

STASHED IN:

9

Most programmers use code that they find online. Including a reference to the source enables future readers to get the full context, such as:

  • what problem was being solved
  • who pr...

1

STASHED IN:

9

Comments should be added not just when initially writing code but also when modifying it, especially fixing bugs. Consider this comment:

// NOTE: At least in Firefox 2, if the user drag...

1

STASHED IN:

8

Sometimes it’s necessary to check in code even though it has known limitations. While it can be tempting not to share known deficiencies in one’s code, it is better to make these explicit, such as ...

1

STASHED IN:

9

Deepstash helps you become inspired, wiser and productive, through bite-sized ideas from the best articles, books and videos out there.

GET THE APP: