News for hackers. Stuff that matters.
Re:Why Not Comments by readthenotes1 on Tuesday September 10, 2024 @06:57PM (#41506466)
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.

Re:Why Not Comments by gus_massa on Tuesday September 10, 2024 @08:15PM (#41506985)

  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.
Re:Why Not Comments by hansvm on Wednesday September 11, 2024 @09:32AM (#41511196)
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.
Re:Why Not Comments by DanHulton on Wednesday September 11, 2024 @12:00PM (#41512621)
One step further:

    DAY_IN_SECONDS = 24 * 60 * 60
Re:Why Not Comments by throwaway14356 on Wednesday September 11, 2024 @11:48PM (#41517409)
SECONDS_PER_MINUTE = 60;

MINUTES_PER_HOUR = 60;

HOURS_PER_DAY = 24;

DAYS_PER_SECOND = SECONDS_PER_MINUTE * MINUTES_PER_HOUR * HOURS_PER_DAY

Re:Why Not Comments by CRConrad on Thursday September 12, 2024 @02:48AM (#41518204)
> 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) ;

Re:Why Not Comments by g-b-r on Tuesday September 10, 2024 @07:58PM (#41506874)
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

Re:Why Not Comments by GianFabien on Tuesday September 10, 2024 @08:26PM (#41507041)
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.
Re:Why Not Comments by dspillett on Wednesday September 11, 2024 @07:11AM (#41510206)
> 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.

Re:Why Not Comments by jjav on Tuesday September 10, 2024 @09:37PM (#41507358)
> 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.

Re:Why Not Comments by dllthomas on Wednesday September 11, 2024 @02:29AM (#41508570)
I once came to a complicated, multi threaded C++ program and saw:

   using namespace std; // using namespace standard
Re:Why Not Comments by f1shy on Wednesday September 11, 2024 @08:06AM (#41510539)
I'm working RIGHT NOW in a codebase where before each function definition there is a comment "// Function"
Re:Why Not Comments by bccdee on Wednesday September 11, 2024 @11:14AM (#41512143)
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.

Re:Why Not Comments by f1shy on Friday September 13, 2024 @11:02AM (#41531882)
With a half decent IDE you do not need it. It is inexcusable.
Re:Why Not Comments by bccdee on Saturday September 14, 2024 @02:09PM (#41541627)
Oh I agree, but the person who put them there must have had some sort of reason, even if it's a bad one.
Re:Why Not Comments by dllthomas on Tuesday September 17, 2024 @01:40PM (#41570405)
> With a half decent IDE you do not need it.

I agree.

> It is inexcusable.

I think it can be quite easily excused on grounds of triviality, though whether that's appropriate may depend on context.

Re:Why Not Comments by throwaway14356 on Wednesday September 11, 2024 @11:25PM (#41517289)
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.