Explain unidiomatic code in comments

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();

// Note that JSONTokener.nextValue() may return

// a value equals() to null.

if (value == null || value.equals(null)) {

return null;

}

Without the comment, someone might “simplify” the code or view it as a mysterious but essential incantation. Save future readers time and anxiety by writing down why the code is needed.

8 STASHED

1 LIKE

Best practices for writing code comments

stackoverflow.blog

MORE IDEAS FROM THE ARTICLE

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 drags outside of the browser window,

// mouse-move (and even mouse-down) events will not be received until

// the user drags back inside the window. A workaround for this issue

// exists in the implementation for onMouseLeave().

@Override public void onMouseMove(Widget sender, int x, int y) { .. }

This helps the reader understand the code and it is helpful for determining whether the code is still needed.

7 STASHED

1 LIKE

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-author Ken Thompson didn’t understand it themselves and later had to rewrite it.

Warning readers away from your code is like turning on your car’s hazard lights: an admission that you’re doing something you know is illegal. Instead, rewrite the code to something you understand well enough to explain or, better yet, that is straightforward.

8 STASHED

1 LIKE

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

8 STASHED

3 LIKES

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 of code that sufficiently explains itself. For example:

return a # Returns a

We can clearly see that 'a' is returned, so there’s no need to explicitly state this in a comment. It adds no information whatsoever and incurs a maintenance cost. This makes comments W.E.T., meaning you “wrote everything twice.”

9 STASHED

1 LIKE

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 a previously written program (or function) without ever having to look at the code, simply by reading the comments.

Commenting is the "art" of describing what your program is going to do in "high level" English statements.

8 STASHED

2 LIKES

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 dictionary of families who live in each city

mydict = {

"Midtown": ["Powell", "Bran"],

"Norcross": ["Mont"]

}

def a(dict):

# For each city

for p in dict:

# If there are no families in the city

if not mydict[p]:

# Print it

print("None.")

This script could have been made simpler by using obvious names for variables, functions and collections.

8 STASHED

1 LIKE

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 with a TODO comment:

// TODO: We are making the decimal separator be a period,

// regardless of the locale of the phone. We need to think about

// how to allow comma as decimal separator, which will require

// updating number parsing and other places that transform numbers to strings

Using a standard format for such comments helps with measuring and addressing technical debt.

8 STASHED

1 LIKE

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 provided the code
  • why the solution is recommended
  • what commenters thought of it
  • whether it still works

For example, compare the follwowing pieces of code:

/** Converts a Drawable to Bitmap. via https://stackoverflow.com/a/46018816/2219998. */

and

// Magical formula taken from a stackoverflow post, reputedly related to

// human vision perception.

return (int) (0.3 * red + 0.59 * green + 0.11 * blue);

8 STASHED

1 LIKE

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

GET THE APP:

RELATED IDEAS

Speaking up in meetings

Group meetings may feel intimidating. Speaking up in meetings is an opportunity to impact developing ideas, but it can also show up your ignorance in front of a large group.

But there are real advantages to speaking up.

  • You may influence ongoing events.
  • Your comments may prompt new ideas in your colleagues.
  • Speaking up gives other people a chance to get to know how you think.

152 STASHED

3 LIKES

How to get more confident speaking up in meetings

fastcompany.com

"May the fourth be with you"

"May the fourth be with you" plays on the phrase in Star Wars "may the Force be with you."

"May the fourth be with you" was popularized by Margaret Thatcher and the United Kingdom's Conservative Party. On May 4, 1979, Margaret Thatcher became the first woman Prime Minister of the U.K. To celebrate, the Tories took out a newspaper ad, which stated, "May The Fourth Be With You, Maggie. Congratulations."

69 STASHED

2 LIKES

How Margaret Thatcher Launched 'May the Fourth Be With You' Holiday

newsweek.com

As already mentioned, debugging is considered a subset of troubleshooting. However, troubleshooting does not always entail solving the problem at that moment in time. There may be procedural constraints or workflow protocols that prevent the issue from being solved immediately. Debugging, on the other hand, is meant to discover and fix a problem all in the same session, whenever possible.

People use the two terms interchangeably, which can add to the confusion

9 STASHED

5 LIKES

Troubleshooting vs Debugging: What’s the Difference & Best Practices

stackify.com