5 ms·

Only "brilliant" code ends up needing comments. Plain code organized into understandable methods (usually no more than half a page of code), with good naming f

by fouc 9y ago

Only "brilliant" code ends up needing comments. Plain code organized into understandable methods (usually no more than half a page of code), with good naming for variables & method names reduces the need for comments. It's also easier to scan/read code if there's a minimum of comments in the way.

vanderZwan 9y ago
There is a ton of code that only exists because of issues elsewhere in the code. This is the opposite of brilliant code: these are the dirty patchworks, the hacks glueing the whole thing together. Yet often these hacks are necessary, at least until some bug is fixed elsewhere. Clear, self-documenting code is great but it can't capture that holistic insight into what the whole program is doing. It can't capture context, because the whole point of clean refactored code is to be as context-free as possible.
- scott_s 9y ago
  Completely agreed. Put another way: the sentiment that code documents itself is only possible in purely logical systems with no edge cases or surprising consequences. As an example, our code base has a comment which refers to our internal issue tracker which itself refers to this HN comment: https://news.ycombinator.com/item?id=9048947 https://news.ycombinator.com/item?id=9048947
  - dhimes 9y ago
    It's also only possible if the code is thought of as a text and is proofread/edited rigorously for reading. My process is 1) write the code quickly- add comments 2) revise for clarity and efficiency (usually modularity), remove comments as confidence allows. This is where I might get the variable and method names correct for self-documenting code. Usually it takes several passes. But most often, "good enough is good enough" and I leave comments in. Just in case.
  - vanderZwan 9y ago
    > which itself refers to this HN comment I was secretly hoping you actually meant your own comment, creating a recursive loop. But a surprise John Nagle is even better
- jakobegger 9y ago
  Also, any non-trivial software project is going to end up needing workarounds for bugs in other software. And you really need to document those. Because otherwise someone is going to remove that second refresh() statement, not knowing that this works around a bug in OS version xyz.
  - vanderZwan 9y ago
    Basically, "IE8 fix"-comments
- RussianCow 9y ago
  > There is a ton of code that only exists because of issues elsewhere in the code. Or sometimes, not even that: issues elsewhere in the system, possibly completely outside of your control (e.g. the language/framework/library you're using, the OS, business requirements, etc).
djsumdog 9y ago
I agree with this. When dealing with a modern programming language, it's just easier to name your functions and variables in such as way that they're readable. It makes sense to document public functions using the language's documentation syntax, if you're writing an API. I look back at a lot of my old code and even without comments, it's easy to follow the logic because I used sensible names and constructs.
- jochung 9y ago
  I have the exact opposite experience. If you find yourself annotating your variables and methods with extra adjectives and nouns, your code isn't simple enough. Those explanations go in code comments. Often it means you can refactor it so that there is only one of any "thing" so there is no need to clarify which version or role this "fooBarThing" is serving to disambiguate it from the other "bazBarThing". Functional composition and well structured data is the key to this. It's basically halfway to point-free style.
  - fouc 9y ago
    The variable name can just be fooBar, and bazBar, and organized/namespaced such that you could have Thing.fooBar and Thing.bazBar (assuming you want those exposed to the rest of the application). Readable variable names doesn't mean wordy names. I would avoid using more than 2 words in a variable name.
- khedoros1 9y ago
  Good, clear code, with nice names and such shows what the code is doing and how it's doing it. It doesn't tell you anything about why it's being done, or the context of the function within the code. You're lucky if you're dealing with code that's either small enough or simple enough not to need the added context...or if you only need to read your old code.
Aaargh20318 9y ago
> Only "brilliant" code ends up needing comments. Code shows what is being done. Comments should explain why it's being done.
- zarex 9y ago
  That's a really nice approach. Thanks for sharing, I might borrow it sometime!
- lackbeard 9y ago
  Code shows how it is being done. Comments should explain what is being done.
  - jessaustin 9y ago
    In some cases it seems that the name of a function takes care of the "what".
golergka 9y ago
Sometimes requirements or quircks of third party library need a comment.
efficax 9y ago
Sometimes things should be commented. Like, for example, every time I have to do pointer arithmetic, I make a comment explaining why, because pointer arithmetic is opaque and error prone.
phamilton 9y ago
I find the better my types are, the less I need to explain. Canonical morphisms generally don't need comments.
gknoy 9y ago
> Only "brilliant" code ends up needing comments. Often you have horrible complexity imposed on you from outside -- business rules you're implementing, etc, which are _not simple_. You can write code that encapsulates a lot of that, and even refactor it so you can see _what_ the code is doing pretty easily ... but it's often _very_ valuable to document in a code comment (docstring, JSdoc, etc) WHY it's like that. Arguably, the comment is not to explain the code, in this case, but rather to explain the twisted bureaucratic logic you're having to implement, so maybe that still counts as "brilliant" code. ;)
lackbeard 9y ago
For an alternate perspective you might find persuasive, I recommend you read through the following slide deck: http://www.sqlite.org/talks/wroclaw-20090310.pdf http://www.sqlite.org/talks/wroclaw-20090310.pdf. (Relevant part starts on slide 80, but I recommend you start from the beginning for full context.)
efsavage 9y ago
For glue/app/ux code that's mostly autocompleted, sure. But for domain-specific, algorithmic, magic-formula type stuff, comments are sanity made manifest.

by fouc 9y ago

vanderZwan 9y ago

There is a ton of code that only exists because of issues elsewhere in the code. This is the opposite of brilliant code: these are the dirty patchworks, the hacks glueing the whole thing together. Yet often these hacks are necessary, at least until some bug is fixed elsewhere. Clear, self-documenting code is great but it can't capture that holistic insight into what the whole program is doing. It can't capture context, because the whole point of clean refactored code is to be as context-free as possible.

scott_s 9y ago
Completely agreed. Put another way: the sentiment that code documents itself is only possible in purely logical systems with no edge cases or surprising consequences. As an example, our code base has a comment which refers to our internal issue tracker which itself refers to this HN comment: https://news.ycombinator.com/item?id=9048947 https://news.ycombinator.com/item?id=9048947
- dhimes 9y ago
  It's also only possible if the code is thought of as a text and is proofread/edited rigorously for reading. My process is 1) write the code quickly- add comments 2) revise for clarity and efficiency (usually modularity), remove comments as confidence allows. This is where I might get the variable and method names correct for self-documenting code. Usually it takes several passes. But most often, "good enough is good enough" and I leave comments in. Just in case.
- vanderZwan 9y ago
  > which itself refers to this HN comment I was secretly hoping you actually meant your own comment, creating a recursive loop. But a surprise John Nagle is even better
jakobegger 9y ago
Also, any non-trivial software project is going to end up needing workarounds for bugs in other software. And you really need to document those. Because otherwise someone is going to remove that second refresh() statement, not knowing that this works around a bug in OS version xyz.
- vanderZwan 9y ago
  Basically, "IE8 fix"-comments
RussianCow 9y ago
> There is a ton of code that only exists because of issues elsewhere in the code. Or sometimes, not even that: issues elsewhere in the system, possibly completely outside of your control (e.g. the language/framework/library you're using, the OS, business requirements, etc).

djsumdog 9y ago

I agree with this. When dealing with a modern programming language, it's just easier to name your functions and variables in such as way that they're readable. It makes sense to document public functions using the language's documentation syntax, if you're writing an API. I look back at a lot of my old code and even without comments, it's easy to follow the logic because I used sensible names and constructs.

jochung 9y ago
I have the exact opposite experience. If you find yourself annotating your variables and methods with extra adjectives and nouns, your code isn't simple enough. Those explanations go in code comments. Often it means you can refactor it so that there is only one of any "thing" so there is no need to clarify which version or role this "fooBarThing" is serving to disambiguate it from the other "bazBarThing". Functional composition and well structured data is the key to this. It's basically halfway to point-free style.
- fouc 9y ago
  The variable name can just be fooBar, and bazBar, and organized/namespaced such that you could have Thing.fooBar and Thing.bazBar (assuming you want those exposed to the rest of the application). Readable variable names doesn't mean wordy names. I would avoid using more than 2 words in a variable name.
khedoros1 9y ago
Good, clear code, with nice names and such shows what the code is doing and how it's doing it. It doesn't tell you anything about why it's being done, or the context of the function within the code. You're lucky if you're dealing with code that's either small enough or simple enough not to need the added context...or if you only need to read your old code.

Aaargh20318 9y ago

> Only "brilliant" code ends up needing comments. Code shows what is being done. Comments should explain why it's being done.

zarex 9y ago
That's a really nice approach. Thanks for sharing, I might borrow it sometime!
lackbeard 9y ago
Code shows how it is being done. Comments should explain what is being done.
- jessaustin 9y ago
  In some cases it seems that the name of a function takes care of the "what".

golergka 9y ago

Sometimes requirements or quircks of third party library need a comment.

efficax 9y ago

Sometimes things should be commented. Like, for example, every time I have to do pointer arithmetic, I make a comment explaining why, because pointer arithmetic is opaque and error prone.

phamilton 9y ago

I find the better my types are, the less I need to explain. Canonical morphisms generally don't need comments.

gknoy 9y ago

> Only "brilliant" code ends up needing comments. Often you have horrible complexity imposed on you from outside -- business rules you're implementing, etc, which are _not simple_. You can write code that encapsulates a lot of that, and even refactor it so you can see _what_ the code is doing pretty easily ... but it's often _very_ valuable to document in a code comment (docstring, JSdoc, etc) WHY it's like that. Arguably, the comment is not to explain the code, in this case, but rather to explain the twisted bureaucratic logic you're having to implement, so maybe that still counts as "brilliant" code. ;)

lackbeard 9y ago

For an alternate perspective you might find persuasive, I recommend you read through the following slide deck: http://www.sqlite.org/talks/wroclaw-20090310.pdf http://www.sqlite.org/talks/wroclaw-20090310.pdf. (Relevant part starts on slide 80, but I recommend you start from the beginning for full context.)

efsavage 9y ago

For glue/app/ux code that's mostly autocompleted, sure. But for domain-specific, algorithmic, magic-formula type stuff, comments are sanity made manifest.