Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

“My Code is Self-Documenting”

ericholscher.com

Post reply on HN
Print view View original

81–90 of 100 posts

Re: “My Code is Self-Documenting”

#81

Post by Fomite »

kyberias wrote: post #49
Fomite wrote: post #42

Earlier quoted context omitted.

All people who write bad code write bad comments = / = All people who write good code write good comments/don't need them.

Well, the point is that people who write good, clean code don't need to comment their code extensively. They don't need to continuously explain why they did some horrible hack or some trivialities because their code is well structured and very easy to understand based on other good software development practices. They don't write the requirements of their functions as code comments, rather they write unit tests that…

I think this ignores the idea that code also has context to it, and that comments even in elegant code are useful not for documenting how a bit of code works, but why that particular thing was done.

Re: “My Code is Self-Documenting”

#82

Post by emodendroket »

derefr wrote: post #17
js8 wrote: post #12

Earlier quoted context omitted.

As others have said.. Code doesn't depend on variable/function names either. Yet you don't argue they fall out of sync, you simply update them. And this should be done for comments, too.

Code does depend on variable/function names. When you change the name at the definition, your code fails to compile until you also change the name at each usage. This is not true of comments. If we could make outdated comments produce compilation errors, we would live in a wonderful world :)

> Code does depend on variable/function names. When you change the name at the definition, your code fails to compile until you also change the name at each usage.

Depends what language you are working in; in some it won't fail until runtime.

Re: “My Code is Self-Documenting”

#83

Post by emodendroket »

derefr wrote: post #13

> Explaining previous approaches that didn’t work; explaining trade offs in the current implementation; marking possible improvements (TODOs) in the code; anything else you’d like to communicate with someone reading or developing the code To me, those are the functions of commit messages , not code comments. Of course, a "proper" IDE (and I don't know of any) would give you the context of the commit messages "impingi…

> To me, those are the functions of commit messages, not code comments.

Yeah, it's definitely much more helpful to have it buried below hundreds of merge commit messages.

Re: “My Code is Self-Documenting”

#84

Post by emodendroket »

sqeaky wrote: post #64
braveo wrote: post #53

Earlier quoted context omitted.

I read code the way you would a book, constructing this model in my head. Comments to me are a big flashing warning sign saying "this is so important, we added extra comments". If the comments aren't really that important it will start hurting my ability to read and understand the code quickly. likewise, if you a comment I wrote, you better sit up and read because it's there for a very good reason. I'm of the opinion…

I agree that accurately reading code is important, but no amount of reading just code tell you why something was done. For a contrived example, why does a specific function/class use an array instead of a dictionary/hash table? A comment explaining that the dictionary was 500x slower in tests could fix that. I suspect that is exactly the kind of comments you would want someone to "sit up and read" but I didn't want t…

Yeah, exactly. If I'm putting comments inside a method (as opposed to the docstring kind of stuff) I'm writing something like "it might seem like it would be better to do [xyz], but that's actually not a good idea because of [abc]."

Re: “My Code is Self-Documenting”

#85

Post by morbidhawk »

> code comments document the why, not the how

While I do agree with this since thoroughly reading the code itself tells you the how I find comments that tell me what it does to be just as helpful as telling why it does it.

I used to fall into the self-documenting code camp back when I programmed in Objective-C and long descriptive names with named parameters made it read like English but as I've read more code in more languages I actually prefer shorter names supported with code comments that tell me clearly in English what the code does.

For instance earlier today I was reading some of the source code in fossil-scm in the check-in.c file. In it there was a function that was simply named `locate_unmanaged_files`. If there wasn't a detailed comment preceding that function I would have assumed it merely found the files and reported on them directly but after reading the comment explaining what it did I realized it stores the files in a temporary SQLite table, after reading that I learned that "locate" had a wider meaning then to just find it and return it but it rather meant that it is now located for any part of the system to find in the database. It would have taken careful reading of the code to have realized this and it helped me to better focus and understand the code I was reading.

Re: “My Code is Self-Documenting”

#86

Post by TheCoelacanth »

RangerScience wrote: post #71
kyberias wrote: post #21

Earlier quoted context omitted.

No. Those are test cases that you put in your unit tests. You don't put data examples as comments in your code.

No. Why make myself or another developer find an entirely separate file in order to comprehend a line (or three) of code? Why leave in a line of code that is all but incomprehensible without an example or explanation? Why provide a paragraph of explanation when a single line of example data will be more informative? Why further decouple the "documentation" from the code itself? Yes, you want test cases, and that's wh…

That's why more languages should let you write tests in the same file as the code it tests like Rust does.

Re: “My Code is Self-Documenting”

#87

Post by ilaksh »

One thing not mentioned is that in an earlier era, code absolutely could not self-document at all. For instance, assembly language in the 80s. Many systems just did not allow for practical longer descriptive names.

Or the traditional C style with extremely long functions that do many things, cryptic names, hardware-related constants or magic numbers, little to no facility for modularization or composability etc.

In that era it was an absolute truism that comments were important. In today's era, comments are usually a symptom.

Re: “My Code is Self-Documenting”

#89

Post by jhlgkhkhil »

codr4life wrote: post #2

I find that the commonly touted opinion that comments should only reflect why, and avoid all duplication; is misguided. The only places where I will elaborate on why is where I can see obvious room for improvement but I'm still waiting for the bigger picture to stabilize, or I'm adding a dependency that I'm not really happy with. Otherwise my comments mostly express the intent of the code in regular prose and have to…

So they quickly fall out of sync with the code and cause more problems than they solve..

Clearly written code already expresses what it does unambiguously. If your code doesn't do what it is supposed to do that is a bigger problem.

Re: “My Code is Self-Documenting”

#90

Post by braveo »

sqeaky wrote: post #64
braveo wrote: post #53

Earlier quoted context omitted.

I read code the way you would a book, constructing this model in my head. Comments to me are a big flashing warning sign saying "this is so important, we added extra comments". If the comments aren't really that important it will start hurting my ability to read and understand the code quickly. likewise, if you a comment I wrote, you better sit up and read because it's there for a very good reason. I'm of the opinion…

I agree that accurately reading code is important, but no amount of reading just code tell you why something was done. For a contrived example, why does a specific function/class use an array instead of a dictionary/hash table? A comment explaining that the dictionary was 500x slower in tests could fix that. I suspect that is exactly the kind of comments you would want someone to "sit up and read" but I didn't want t…

That's specifically why I said documentation gives the context. Why the API uses a hash table instead of an array is something for the documentation of said API, not code comments.
Post reply on HN