`three = 1` in the linux sourcecode • Hacker News Board

Re: `three = 1` in the linux sourcecode

#61

Post by grannyg00se » Tue, Feb 25, 2014, 2:49 PM UTC

simias wrote: post #3

Read the comment above ext4_list_backups right above: https://github.com/torvalds/linux/blob/d158fc7f36a25e19791d2... /* * Iterate through the groups which hold BACKUP superblock/GDT copies in an * ext4 filesystem. The counters should be initialized to 1, 5, and 7 before * calling this for the first time. In a sparse filesystem it will be the * sequence of powers of 3, 5, and 7: 1, 3, 5, 7, 9, 25, 27, 49, 81, ... * F…

"as long as it's commented correctly there's no issue"

How do you know it is commented correctly? Now you have to understand the code and the comment and mentally confirm them to be in sync. You also have to maintain the comment when you make changes to the code and you have to trust that others are going to do the same.

It would be better if the code itself was expressive enough so that a comment wasn't needed.

Re: `three = 1` in the linux sourcecode

#62

Post by army » Tue, Feb 25, 2014, 2:59 PM UTC

apaprocki wrote: post #48

_pmf_ wrote: post #42

Earlier quoted context omitted.

> Why don't you all "deserves better comment" people send a patch? Trying to get a patch into Linux as a new developer without personally knowing one of the (sub-)lieutenants is a futile exercise.

I did it (and repeated a few times) and I didn't know anyone. I did it by reading about the process, formatting my patch correctly, and sending it to the appropriate list. If it were so difficult, Linux would not be a success. Now, just like other large projects, maintainers might dislike comment-only nit patches, but if it objectively increases readability it might work.

It's probably easier to get it in when you're solving a real problem.

Re: `three = 1` in the linux sourcecode

#63

Post by codereflection » Tue, Feb 25, 2014, 3:23 PM UTC

koverstreet wrote: post #56

/yawn https://github.com/torvalds/linux/blob/d158fc7f36a25e19791d2...

The comment on that function is a bit more entertaining than the original post.

Re: `three = 1` in the linux sourcecode

#64

Post by Vextasy » Tue, Feb 25, 2014, 3:24 PM UTC

Seems like a perfectly reasonable naming scheme to me. Anyone foolish enough to think that the variables are there to hold the values 3, 5 and 7 is probably wasting their time on the code in the first place.

Besides, it made you read the code and the comments.

Re: `three = 1` in the linux sourcecode

#65

Post by gus_massa » Tue, Feb 25, 2014, 3:25 PM UTC

troels wrote: post #49

h2s wrote: post #8

Earlier quoted context omitted.

See this comment: https://news.ycombinator.com/item?id=7296586 Good commenting is no substitute for good naming. For a variable containing the number 1, "three" is a shitty name.

I don't know. Upon seeing a variable named "three", I wouldn't immediately assume it contained the literal number 3, since that would be rather pointless use of a variable. It's an odd name, but I don't think it'll be mistaken for its literal meaning.

The LaTeX source code has definitions for the constants \@ne, \tw@, \thr@@. It's a microoptimization that is useful because of the way the TeX/LaTeX parsers work. I don't understand the details, it's beyond my LaTeX wizardry. http://tex.stackexchange.com/questions/9787/ne-tw-thr

On the other hand, I think that this kind of definitions are not useful for C.

Re: `three = 1` in the linux sourcecode

#66

Post by orclev » Tue, Feb 25, 2014, 3:48 PM UTC

dangrossman wrote: post #32

Syssiphus wrote: post #18

Earlier quoted context omitted.

A perfect example of a missing code-comment.

The explanatory comment is 40 lines earlier in the same file where the function those variables are being passed to is defined. It need not be repeated every couple lines; "being clear to outsiders linked to a specific line of a specific file without context" is not a reasonable concern.

The function declared earlier is perfectly fine, the comment is sufficient to explain what it's doing, but functions should be understandable simply by reading their source and in that respect the linked function fails. This would be really simple to solve with a simple comment, E.G.

  // current power of three, init to 3^0
  unsigned three = 1;

The fact that this looks like a bug at first glance is a pretty good indication that there should be some explanation of what exactly it's doing.

Re: `three = 1` in the linux sourcecode

#67

Post by awda » Tue, Feb 25, 2014, 3:55 PM UTC

orclev wrote: post #66

dangrossman wrote: post #32

Earlier quoted context omitted.

The explanatory comment is 40 lines earlier in the same file where the function those variables are being passed to is defined. It need not be repeated every couple lines; "being clear to outsiders linked to a specific line of a specific file without context" is not a reasonable concern.

The function declared earlier is perfectly fine, the comment is sufficient to explain what it's doing, but functions should be understandable simply by reading their source and in that respect the linked function fails. This would be really simple to solve with a simple comment, E.G. // current power of three, init to 3^0 unsigned three = 1; The fact that this looks like a bug at first glance is a pretty good indicat…

This is actually contrary to Linux kernel "good style". Functions should be short and understandable. Comments should be on the top of the function, describing what the function is for. Comments describing variables in functions are discouraged.

Re: `three = 1` in the linux sourcecode

#68

Post by Navarr » Tue, Feb 25, 2014, 3:58 PM UTC

dangrossman wrote: post #32

Syssiphus wrote: post #18

Earlier quoted context omitted.

A perfect example of a missing code-comment.

The explanatory comment is 40 lines earlier in the same file where the function those variables are being passed to is defined. It need not be repeated every couple lines; "being clear to outsiders linked to a specific line of a specific file without context" is not a reasonable concern.

But it is! God forbid the original function disappear or change completely and the function below it loses all context and description.

Re: `three = 1` in the linux sourcecode

#69

Post by spinlock » Tue, Feb 25, 2014, 4:01 PM UTC

annnnd wrote: post #54

dangrossman wrote: post #32

Earlier quoted context omitted.

The explanatory comment is 40 lines earlier in the same file where the function those variables are being passed to is defined. It need not be repeated every couple lines; "being clear to outsiders linked to a specific line of a specific file without context" is not a reasonable concern.

In this case I think it is not about comment at all - it is about poor naming. More descriptive (or less misleading) var names would help in this case.

I agree. 'power_of_three' isn't really that much of a hardship to type and it obviates the need for a comment.

Re: `three = 1` in the linux sourcecode

#70

Post by spinlock » Tue, Feb 25, 2014, 4:05 PM UTC

VierScar wrote: post #35

keypusher wrote: post #22

If only there was a system for fixing the code yourself instead of having to post about it to a widely read tech site.

It's not a bug, as shown by the currently top comment. It is however, misleading and could be better documented or named. Still, it is at least a little amusing, worth posting here?

I think its worth posting. It's the first piece of code I've seen on hacker news in a while. It also makes a great point about good variable names making code clear.