Hacker News Reader

Comment by flatline3 | Hacker News Reader

I prefer code where I can skim the comments and see the major plot points, at a glance.

If you need to skim the comments to see how a function is doing what it's doing, the function is too long.

When it can take 3-4 statements to perform a single logical operation, there is still value in summarizing each block with a comment, even if the function isn't "too long".

That's what function names are for. Comments don't need to summarize. A useful comments says why code is this way, it doesn't summarize or repeat code.

> That's what function names are for.

A single function for every 3-4 line operation would result in incredibly disjointed code, and would require more explicit documentation of invariants because that function can now be called elsewhere (at least inside of the given translation unit).

> A useful comments says why code is this way, it doesn't summarize or repeat code.

That's nonsensical. Why wouldn't you want to abstract the complex?

I abstract code with code, not with comments. Comments in general stink, and are used to express what code can't. If I can express it in code, it doesn't need a comment. Every comment is a sign that you failed to write expressive code.

If you need a comment to say what the next four lines do, you need a function for that, not a comment.

Functions have maintenance and implementation overhead. They define an API that is accessible from the translation unit, and they thus require defining some amount of invariants. They also require breaking flow from the current function being implemented to hoist the code upwards.

A short, atomic unit of 4-6 lines of code does not deserve to be a function simply because it's an atomic unit, but it does warrant a simple comment that someone skimming the code can use as an index to determine where they want to look.

It's all about making the code approachable in bite size pieces for future maintainers, your collaborators, and your future self. Breaking it into pieces and describing the code means that maintainers are not required to trace out all the code and swap in a huge amount of knowledge just to determine what a given function does, and why, and what is safe to change within it.

> A short, atomic unit of 4-6 lines of code does not deserve to be a function simply because it's an atomic unit

And I couldn't disagree more with that statement, and virtually everything you've said. Maintainers don't need to look at a function to see what it does, that's what its name tells you and keeping functions focused on doing one atomic thing is what allows the name to replace the implementation and makes for well written programs. I despise programs written in the style you suggest.

A well written program is a thousand small functions/methods unburdened by long methods full of comments. Good code requires few comments other than those that explain implementation choices or class responsibilities. Comments are a code smell most of the time, they exist to make up for poorly written code.

I mostly agree, but "they exist to make up for poorly written code" should be "they exist to make up for less maintainable code." Less maintainable code may not be poorly written if other constraints (intense optimization in a critical path, for instance) force it on you.

Well, I did say to explain implementation choices which I think covers your point, as I do agree with you.

Yeah, I was just objecting to the implicit (and quite possibly unintended) value judgment.

Sure, I do like your phrasing better, less maintainable code.

Maybe the compiler needs to see the whole function in order to properly optimize register usage, because the function is on the critical path.

There is sometimes more to code than readability, unfortunately. I have worked with functions thousands of lines long that can't be broken up without losing a few percentage points of speed - but these functions are called millions of times.

Effective use of macros or inlining could solve that problem.

Over 2,000 lines with macros. Inlining didn't give good enough results (at the time).

It's always a matter of heuristics, for sure. When you need to modify code in a way that's less than readable/obvious, then you start dropping in comments to compensate. Your first pass should be understandable and obvious and readable, with comments typically restricted to documenting functions and interfaces.

You would actually write an "Increment the total" comment?

That example is rather hyperbolic and not particularly useful. I can't recall the last time in 15 years that I thought "this code has too many comments!"

Back in college I was a teaching assistant for CS classes and graded a lot of what was very often very poorly written and majorly undercommented code. But I do remember once getting an incredibly unnecessary 2 page long comment for a 10 line function.

That may be the only time that thought has gone through my head.

At my first internship, the code base had basically no comments in it, but was in general very clean, very organized, and there was a ton of thought put into naming and organization for readability. It was a good exercise for me working like that because it forced me to not rely on comments to explain messy code. But I also remember having long debates about what to name a variable to make it perfectly clear to the next person reading this code what it does (and often times ending up with excessively long variable names) and thinking "wow...this is a waste of time. You could just add a 1 line comment"

"I can't recall the last time in 15 years that I thought "this code has too many comments!""

I've thought that every time I see a source file that contains an automatically generated header built from the revision history.

Consider the standard Java cough paradigm used by multitudes of developers, and on by default in many Java IDEs:

    /* Gets the person's name
       @returns the person's name */
    public String getName() {
       return name;
    }

That is insane. The comment adds nothing to anyone's day and helps no one better understand the method than after simply reading the method signature.

It generates auto-docs, which are useful. It's just a ridiculously verbose way to do it, and it would be preferable if the documentation could be generated without the repetitive comment.

I probably wouldn't write "increment the total", but I think it makes sense to comment on what the total is/represents, or why the total is incremented in some particular way (if it's non-obvious).

My beef with "increment the total" comments is not that they are there, but rather that they don't help me get the big picture.

Some people certainly do! My favorite examples of how not to write comments are these code snippets from the API guide I was given at a previous job. The other 60 pages of API documentation are just like this- all what and no why.

The problem isn't that these comments are harmful (they're not), but that inserting these comments made the coder feel like they'd done their job of commenting their code well, when in actuality the comments provide no insight to why certain things are called or instantiated, or what certain values represent; critical knowledge one needs to extend the code beyond the specific example cases the API guide presented.

----

  ‘ A for loop iterates through each row of DataGridView
  For Each row In DirectCast(Me.DataGridView1.Rows, IEnumerable)

----

  Dim frmTakeBackTask As New TakeBackTask
  ‘ Public oTaskData of TaskBackTask gets populated from the local object oTaskData
  frmTakeBackTask.oTaskData = oTaskData

----

  ‘ A For loop is initiated to iterate through each child node contained 
  ‘ in the XML document
  For Each record In xmlDoc.ChildNodes.ItemOf(0).ChildNodes
      ‘ A nested For loop is initiated to iterate through each column
      For Each column In record.ChildNodes

Reply on news.ycombinator.com