Hacker News Reader

Comment by rckrd | Hacker News Reader

Author here, thanks for posting.

Here's some more color on the reflection on comments, straight from the Linux Kernel documentation that capture my intention much better:

"Comments are good, but there is also a danger of over-commenting. NEVER try to explain HOW your code works in a comment: it’s much better to write the code so that the working is obvious, and it’s a waste of time to explain badly written code.

Generally, you want your comments to tell WHAT your code does, not HOW. Also, try to avoid putting comments inside a function body: if the function is so complex that you need to separately comment parts of it, you should probably go back to chapter 6 for a while. You can make small comments to note or warn about something particularly clever (or ugly), but try to avoid excess. Instead, put the comments at the head of the function, telling people what it does, and possibly WHY it does it."[0]

[0] https://www.kernel.org/doc/html/v4.10/process/coding-style.h...

View on HN

> NEVER try to explain HOW your code works in a comment

Never is a strong word, sometimes the algorithm is just inherently complex and it's worth it to explain what you are doing.

Why is much more important, but it's also partially solved automatically by git blame and adding the task number to each commit message (and writing good commit messages which IMHO is more important than writing good comments). Each line of your code has commit message associated with it whether you care about it or not - make it useful.

Yeah algorithms in particular are where I'm hesitant to say "never explain how your code works." They can be dense, deeply-nested, and hard to break down into semantically-meaningful variables and function names. Sometimes it's good to explain what's going on there.

That's what people don't understand. We don't think in code, we have a translation layer from human language/thought that we think through when parsing a programming language. As long as the comments are kept accurate, they can greatly improve your ability to parse through a block of complex code, which is crucial when you're trying to hotfix an issue. It also gives newer programmers to the codebase a chance to help understand what that block of code is doing beyond it just being some blackbox with an input and output.

Yeah the how is important when auditing the correctness of code. I would say "Never listen to an advice about never doing something, there is always a case were breaking the rules is good"

From the linked post:

> Know when to break the rules.

This is generally how I treat comments, docblocks on everything for api documentation, but inside functions, yeah, something clever or non-obvious gets a comment. I also tend to document complex interfaces / abstract classes more heavily to give people a sort of road map for implementing it.

It makes more sense if you emphasise COMMENT as well.

> NEVER try to explain HOW your code works in a COMMENT

Comments are for explaining why, not how. If some code is algorithmically complex enough to need explanation, that should go in documentation, not an inline comment.

Comments are documentation.

I've never seen or heard of a team that keeps documentation for their complex algorithms. It's just not done.

And if it was, I'd bet that they get out of date very fast

One thing a friend of mine (hi Adrian!) did at my old workplace, that I found incredibly annoying at the time, but later realised was exactly the right thing to do, was set up a wiki for us to use and then refuse to answer any question or acknowledge any information except via that wiki. After a while I just gave in and before telling him about anything, stuck it on the wiki. Years later when I left, every time anyone asked me a question I could honestly answer "it's on the wiki."

People love to hate on Bezos (less here than elsewhere, though, I guess) but this is exactly the tack he used to convert Amazon's IT setup to services, and I think both were shrewd moves.

I have been trying to explain this for some time and I’ve just had a new thought so I will add it here.

I think that we fundamentally start to lose the mental distinction between the language semantics and the idiomatic code. It’s all part of the scenery. So for a seasoned programmer, the what and the how blur together. There is no how to getting a value from an object, a struct, a tuple, or an array. You just do. Unless your language doesn’t have one of those things.

Non-idiomatic code is full of how. So what we seek is code that just tells us “what” and comments are a bargain we make with each other to guarantee a lower bound on that. Meanwhile the self documenting code people want a different arrangement, where you have to stoop to documentation less often by putting that energy into sustaining a constant output of idiomatic code.

Most nontrivial algorithms are just a bunch of nested for loops with array indexing and ifs mixed in. There were no advances in computer science that made this kind of stuff less confusing as far as I am aware. We made a lot of advances to make simple boring business code do 30 nested method calls, but at the end of the day the basic algorithm is still a bunch of loops and ifs.

It's actually funny how all the focus in CS seems to be on modeling the business part in more natural ways, while the "solving problems" part is still done like it's 1970s.

You can make the algorithms clearer with good variable names and extracting some parts to well named methods (and you should, usually) but it's often not enough.

Example taken straight from Wikipedia:

    function BellmanFord(list vertices, list edges, vertex source) is

        // This implementation takes in a graph, represented as
        // lists of vertices (represented as integers [0..n-1]) and edges,
        // and fills two arrays (distance and predecessor) holding
        // the shortest path from the source to each vertex

        distance := list of size n
        predecessor := list of size n

        // Step 1: initialize graph
        for each vertex v in vertices do
            distance[v] := inf             // Initialize the distance to all vertices to infinity
            predecessor[v] := null         // And having a null predecessor
    
        distance[source] := 0              // The distance from the source to itself is, of course, zero

        // Step 2: relax edges repeatedly
        repeat |V|−1 times:
            for each edge (u, v) with weight w in edges do
                if distance[u] + w < distance[v] then
                    distance[v] := distance[u] + w
                    predecessor[v] := u

        // Step 3: check for negative-weight cycles
        for each edge (u, v) with weight w in edges do
            if distance[u] + w < distance[v] then
                error "Graph contains a negative-weight cycle"

        return distance, predecessor

This is pseudocode with some stuff abstracted away, yet they still added "what" comments. You can remove some of them and split it into several methods but for Step 2 I still kinda feel it's not enough information to make it obvious what is happening. What does it mean to "relax an edge"? Why do we need to do it V-1 times? Does order matter?

I don't think fancy programming language features help here. You can change iteration into tail recursion or point-free functional code or whatever is fashionable but the underlying complexity remains.

And there are algorithms out there that are much trickier.

Source: https://en.wikipedia.org/wiki/Bellman%E2%80%93Ford_algorithm...

To an extent List Comprehensions are, if not a fix, at least an analgesic. But FP is definitely a case of The Future is Here, It's Just Not Evenly Distributed. Calling it an 'advance' might be a stretch, at this point. Lost wisdom?

I would chalk the complexity of the example you provided up to the inability of half of developers to handle four nested conditionals, and for most of the rest to handle five.

I sort of handwaved over the Death By A Thousand Cuts scenario, which I definitely believe is important. It doesn't matter how idiomatic your code is if you have enough of it. I don't maintain that idiomatic code is free by any means. It just doesn't have the factorial surface area of spaghetti code. It scales better, but scale absolutely matters.

If you count conditional branches, you'll see that parts of this code are pushing up against those limits. You're definitely into 'how' territory, but you've also shunted it off to a function that just 'does stuff'. So my code that relies on this for step 1 of a bigger answer doesn't give a shit (as long as the answer is correct, including boundary conditions).

Code doesn't exist in a vacuum, it exists in the context of our general knowledge.

I would argue that the only comment really useful here would be one pointing to the paper/wikipedia article/whatever that explains the algorithm.

If no such article/reference exists and/or your implementation has nuances you want to explain, that's where technical documentation should come in. For instance, check the linux kernel's explanation of circular buffers and how to use them [1].

[1] https://github.com/torvalds/linux/blob/master/Documentation/...

> What does it mean to "relax an edge"? Why do we need to do it V-1 times? Does order matter?

These are questions related to understanding the algorithm, not the implementation. There are much better ways to convey that information (including examples, diagrams, lengthy explanations, etc.). Trying to convey that information through comments in an implementation is an exercise in __not__ using the best tool for the job ;)

Don’t agree. Longer pieces of code are way easier to reason about. Deep function nesting, which seems clean is very confusing mentally, and also difficult to describe in terms of function name.

Explain *why* you’re doing something a certain way. This also includes a little bit of how and what. Other than that, just make sure your business terms are reflected in the code, or at least have a proper definition of things, which you can easily reason about.

Agreed. When looking at complex code, it can be helpful to expand the functions inline to be able to view all of it in a single screen flow. Switching between too many files and functions sometimes creates friction, making it more difficult.

However, when writing the code if a section of code is repeated more than 2 times, it should be considered to break it out into a separate function with a useful name.

Unless you’re doing something like performance analysis, I think needing to peek into the definition of a function to understand a piece of code is a smell: it indicates that the function is only abbreviating and not providing an abstraction.

Well a lot of the time when you are looking at something you are trying to diagnose some problem or another, which means you want to be 100% sure of what something is doing. Even if the function provides a good abstraction you might still want to make sure that it is doing exactly what it says on the tin because you are desk checking some weird behaviour and you want to make sure each step is acting correctly

Agreed, but that means you verified that the use site was correct and are now examining whether the abstractions it depends on were implemented correctly.

My point is just that you shouldn’t normally have to keep both sides of a call site in mind at once.

Eh, to each their mental models. I have much less trouble understanding nested and, some may say, very-class-segregated code than mostly procedural one as the general shape of the code + the pattern names used generally gets me 95% of where I have to be to understand what is the issue at hand. But then I found out that not a lot of people draw diagrams when they are coding ? (Which in my case helps immensely - and after some time you can just draw the diagram in your head)

I've always felt like this is where IDEs could help. You should be able to "inline" the implementation of a function or even whole class without actually changing the code.

I've always felt the same, so I recently made an interactive mock-up of such an IDE feature: https://emilprogviz.com/expand-calls/?inline,substitution Not mobile friendly, best seen on desktop. To inline a function call, either click the "+" icon, or go up/down with the keyboard and press spacebar when the caret is on that line.

(There's also a video where I explain the reasoning behind the mock-up, but I guess the motivation is already blatantly obvious to most readers of the above discussion, so feel free to skip the first chapters: https://youtu.be/wdf6S6oumH8 )

Then I learned that the Smalltalk editor Pharo has a similar feature! Seems many people have the same idea. Today's major IDE makers should have copied this feature already!

They may be easier in some cases to reason about - which is great until you start writing tests.

Once you start writing tests you find that the size of test functions will reflect the size of the function you're testing. The test functions start to have huge set-ups in order to test a small bit of logic, and you end up spending a lot of time fixing tests every time you make a change to that function.

This is why it's often better to find ways to make functions smaller.

There is a difference however of people refactoring code into smaller classes / functions vs what I'd call "hiding" code in classes / functions. If all someone has done is broken a large function into a chain of functions then of course that is not good.

When people refer to small functions / classes they refer to breaking up the concepts that a class / function represents into smaller concepts that build upon one another. This also increases the reusability of code.

So in short - I agree, longer pieces of code can be better for reasoning about, but I disagree that that necessarily makes them better.

I worked with a guy who liked writing little <10 line functions, deeply nested, in dozens of files. Each individual function was nice and easy to read but figuring out what the entire call tree was doing required hours of archaeology.

Edit: He also refused to ever delete any code he'd written "because it might be useful later." I once spent three hours tracing the source of some values, only to discover that the output of the entire call tree I was working my way through was being quietly thrown away at the end.

The WHY is also very useful in comments, especially in business/UI/glue code where special cases abound.

I would say the why might be more important than the what a lot of the time

Came here to comment along those lines.

The WHY often will be elaborate enough that it deserves a design document that includes things like: who is the owner of those requisites, what is the rationale behind them, who are the stakehilders who signed off, what interactions it has other components, what alternative designs were considered, etc.

This. And in particular if there are multiple ways to do it, and you had to choose a particular way for a reason.

Comments should explain the decision process (if one was necessary) that lead to this variant. Because if there's no comment explaining it, the next developer looking at it will say "oh, but it's much simpler if I just do it that way", and will run into trouble because he didn't realize the pitfalls.

What's your take on the difference between explaining how code works and describing what it does?

I only ask because of bits like the TCP rate estimator sometimes have step by step comments that might be interpreted as explaining how the code is doing something.

For example take the app limited detection function: https://github.com/torvalds/linux/blob/master/net/ipv4/tcp_r...

My take is that step by step commented explanations make sense when it's something either extremely complicated or making use of a system or tech that's not widely known.

Otherwise, clearer code, smaller methods and better variable/method names are the way to go imo.

The exception to the WHAT/HOW divide is working around a 3rd party bug. Documenting workarounds can help prevent reintroducing the same bug when someone edits or copies the code. This can be especially helpful if the 3rd party bug gets fixed in such a way that your workaround now fails.

> try to avoid putting comments inside a function body

This makes me sad. Think about others who will have to reverse engineer your code. Not every functionality should be split into a function, unless you want to add 10 layers of abstraction and misdirection.

I prefer over-commenting a lot, over under-commenting.

The only harm is, when you miss the important bits over too much blabla, or when you forget to update comments. There are not many worse things, than wrong documentation/comments.

"you want your comments to tell WHAT your code does, not HOW" but I agree very much to this.

I've seen this interpreted by smart engineers in a counter-productive way, in that they believe their code is so good that none of it ever needs any comments and hence they never write them despite the fact that their code isn't all that clear. It's more hubris than anything.

Otherwise, there are many techniques you can use to make the code self-explanatory. I've taken a comment before and restructured the code to literally read like the comment.

It’s an old assertion of the Refactoring community that a commented block in the middle of a function is a separate function trying to break free. If the code is interesting in its own right, move it.

That also extends to how. If the algorithm is interesting or complex enough you should move it as well, as the point of the host function is not to show how clever you are, but to accomplish a task.

Empirically I’ve found that I get much less pushback on algorithmic tweaks when I isolate them to a separate function. The reader doesn’t have to include them in their local reasoning, and I suspect but cannot prove that they tell themselves that they can always revert that code cleanly, so let’s just leave it be for now and see what happens.

Interesting reading about RuneScape in your post. I got into programming because of RuneScape and writing bots! Great memories.

I enjoyed reading this post. Cheers!

Thanks! Likewise. Truly a great sandbox for budding programmers.

I got into programming at 14 because of writing scripts in Gemstone, a text based MMOMUD. Didn't even realize what I was doing was programming until college though...

Gemstone! That game changed everything for me

Writing increasingly sophisticated bots and trying to figure out what exactly would earn you a ban was my own first practical experience with coding.

I mostly managed to dodge bans on my most used accounts at the time, but interestingly when I checked back a year or two ago the majority had been permanently suspended. I wonder if they have some method of retroactively determining if someone was botting?

I think sometimes you want to put why in a comment. Just today I wrote a two paragraph comment (usually I don't write many comments at all) that describe the business need for why this the code is necessary (in my case, connecting to a 3rd party data source that overshares, describing the nature of the oversharing, outlining the -- very complex -- steps in the pruning algorithm, and noting that there are corner cases we might miss and also noting that we shouldn't care -- a handful of bad apples in a machine learning algo will probably disappear in the wash).

Yup, I rarely ask "what's this code do" or "how does this code do that".

But "why the fuck" is a daily occurrence.

Self documenting code explains how and what. If you need a comment to explain how and what its a code smell. Sometimes it's ok but ideally it should be rare.

I try not to overcomment but when I write code that looks confusing or clever I try to explain why I've done it that way.

If I'm optimising, I'll explain why.

If I'm making an assumption about something related but elsehwere I'll explain that.

If I'm leveraging some context that isn't explicit, I'll explain that.

...

Also, type of code matters, glue code rarely needs exhaustive comments.

Library code often gets line by line commentary so when someone comes in to change something for their use case they have a clear understanding of what they're really changing, and who and what might break because of their change.

I notice library code tests often get more comments explaining what and why I'm adding an assertion.

Glue code test rarely needs comments in tests.

Another reasonable exception is referencing external sources - whether it's a specific library you borrowed code from, a piece of documentation needed to better understand what's going on, or a reference to a SO post explaining some weird workaround you've implemented.

The best comments are about intent. I can read the code and tell you what it does, but I have no idea if that's what it's supposed to do without knowing the intent.

Define "comments".

Like many arguments, disagreements below are mostly not disagreements about facts but disagreements of definitions at heart, only masquerading as disagreements about facts.

Beyond a trivializing definition of "whatever follows a #", each time the word "comments" appears in the discussion below, it seems to actually refer to something entirely different from one person to the next.

"Comments are good, but there is also a danger of over-commenting."

IMHO The only way to tell if you are able to comment well is to do this: Work on some project - then in 2 years come back to that project and add a feature to it. You will learn real quick how good your comments are. Spoiler alert: You wont care about "how" - you will want to know "why".

> tell WHAT your code does, not HOW

And also Why.

I personally like an executive summary of the code, ie, I just got to this file, what am-I looking at.

Small typo, it's "Malcolm Gladwell in Outliers" not "Outsiders", I particularly noted it because I learned the word "outliers" in English thanks to that book.

Thanks, fixed!

Reply on news.ycombinator.com