undefined | Better HN

0 pointsreadthenotes11y ago0 comments

I have regretted when you fail to follow that lesson.

I did a survey once in about 3/4 of the comments were either wrong or useless. Examples:

//Add 1 to x

x+=1;

//Add 1 to x

x+=2;

//Seconds per normal day

x = 86400;

"Why not" comments are incredibly valuable except they suffer from explanatory decay as much as other comments.

The hope behind Intention Revealing Names is that the dissonance will be too great for the subsequent developers to ignore when they change the code.

Of course, that isn't always true.

0 comments

gus_massa1y ago

  x = 86400

If I were forced not to write comments, I'd write that as

  x = 24 * 60 * 60

and let the compiler optimize that.

hansvm1y ago

When writing it inline, I like this approach. I like even better when these things have names. Something like `std.time.s_per_day` or `time_utils.s_per_day`. Then in the one place they're defined, use a pattern like the above to make them easy to reason about.

DanHulton1y ago

One step further:

    DAY_IN_SECONDS = 24 * 60 * 60

throwaway143561y ago

SECONDS_PER_MINUTE = 60;

MINUTES_PER_HOUR = 60;

HOURS_PER_DAY = 24;

DAYS_PER_SECOND = SECONDS_PER_MINUTE * MINUTES_PER_HOUR * HOURS_PER_DAY

CRConrad1y ago

> DAYS_PER_SECOND = SECONDS_PER_MINUTE * MINUTES_PER_HOUR * HOURS_PER_DAY

Naah.

DAYS_PER_SECOND = 1 / (SECONDS_PER_MINUTE * MINUTES_PER_HOUR * HOURS_PER_DAY) ;

jjav1y ago

> I did a survey once in about 3/4 of the comments were either wrong or useless.

> Examples:

> //Add 1 to x

> x+=1;

If 3/4ths of comments are like this, maybe show a sampling of public source code (e.g. from github) that shows how prevalent comments like this are in any real codebase.

I've been programming since 1982 and have never seen this type of "add 1 to x" comment in real code, outside chapter 1 of some intro to programming book.

throwaway143561y ago

I would write that comment if it was a long enough list of single line var assignments with enough complex ones that each have a comment like this one.

I will als name each db table column in the correct order by its correct name right above that what decided the value.

// id

user_id = getUserId();

They serve as dividers.

dllthomas1y ago

I once came to a complicated, multi threaded C++ program and saw:

   using namespace std; // using namespace standard

f1shy1y ago

I'm working RIGHT NOW in a codebase where before each function definition there is a comment "// Function"

bccdee1y ago

I wonder if that's intended for a specific workflow, e.g. ctrl-f "Function" enter-enter-enter-enter to cycle through all the functions in the file.

That's the only reason I can think of for writing those comments.

1 more reply

g-b-r1y ago

An outdated comment is at least a very strong signal that the code might be wrong

And, you definitely had little experience with under-documented code

GianFabien1y ago

For me the quality of comments, somewhat based on the metrics that @renhanxue mentions, is a code smell. If code is poorly commented (by my standards) then I treat the actual code with suspicion.

dspillett1y ago

> An outdated comment is at least a very strong signal

Also: if the code and the comments appear to disagree, there is a reasonable likelihood that both are wrong in some way.

j / k navigate · click thread line to collapse

0 comments

gus_massa1y ago

  x = 86400

If I were forced not to write comments, I'd write that as

  x = 24 * 60 * 60

and let the compiler optimize that.

hansvm1y ago

DanHulton1y ago

One step further:

    DAY_IN_SECONDS = 24 * 60 * 60

throwaway143561y ago

SECONDS_PER_MINUTE = 60;

MINUTES_PER_HOUR = 60;

HOURS_PER_DAY = 24;

DAYS_PER_SECOND = SECONDS_PER_MINUTE * MINUTES_PER_HOUR * HOURS_PER_DAY

CRConrad1y ago

> DAYS_PER_SECOND = SECONDS_PER_MINUTE * MINUTES_PER_HOUR * HOURS_PER_DAY

Naah.

DAYS_PER_SECOND = 1 / (SECONDS_PER_MINUTE * MINUTES_PER_HOUR * HOURS_PER_DAY) ;

jjav1y ago

> I did a survey once in about 3/4 of the comments were either wrong or useless.

> Examples:

> //Add 1 to x

> x+=1;

If 3/4ths of comments are like this, maybe show a sampling of public source code (e.g. from github) that shows how prevalent comments like this are in any real codebase.

I've been programming since 1982 and have never seen this type of "add 1 to x" comment in real code, outside chapter 1 of some intro to programming book.

throwaway143561y ago

I would write that comment if it was a long enough list of single line var assignments with enough complex ones that each have a comment like this one.

I will als name each db table column in the correct order by its correct name right above that what decided the value.

// id

user_id = getUserId();

They serve as dividers.

dllthomas1y ago

I once came to a complicated, multi threaded C++ program and saw:

   using namespace std; // using namespace standard

f1shy1y ago

I'm working RIGHT NOW in a codebase where before each function definition there is a comment "// Function"

bccdee1y ago

I wonder if that's intended for a specific workflow, e.g. ctrl-f "Function" enter-enter-enter-enter to cycle through all the functions in the file.

That's the only reason I can think of for writing those comments.

1 more reply

g-b-r1y ago

An outdated comment is at least a very strong signal that the code might be wrong

And, you definitely had little experience with under-documented code

GianFabien1y ago

For me the quality of comments, somewhat based on the metrics that @renhanxue mentions, is a code smell. If code is poorly commented (by my standards) then I treat the actual code with suspicion.

dspillett1y ago

> An outdated comment is at least a very strong signal

Also: if the code and the comments appear to disagree, there is a reasonable likelihood that both are wrong in some way.

j / k navigate · click thread line to collapse