Skip to main content
Software Engineering

You are not logged in. Your edit will be placed in a queue until it is peer reviewed.

We welcome edits that make the post easier to understand and more valuable for readers. Because community members review edits, please try to make the post substantially better than how you found it, for example, by fixing grammar or adding additional resources and hyperlinks.

Required fields*

6
  • 6
    One useful place for comments: in scientific code, you can often have computations that are quite complex, involving lots of variables. For the sanity of the programmer, it makes sense to keep variable names really short, so you can look at the maths, rather than the names. But that makes it really hard to understand for the reader. So a short description of what is going on (or better, a reference to the equation in a journal article or similar), can be really helpful. Commented Sep 1, 2014 at 8:50
  • 1
    @naught101: yes, especially since the paper you're referring to also probably used single-letter variable names. It's usually easier to see that the code does indeed follow the paper if you use the same names, but that's in conflict with the goal of the code being self-explanatory (it's explained by the paper instead). In this case, a comment where each name is defined, saying what it actually means, substitutes for meaningful names. Commented Sep 1, 2014 at 8:56
  • 1
    When I am searching for something specific in code (where is this specific case handled?), I don't want to read and understand paragraphs of code just to discover that it is not the place after all. I need comments that summarize in a single line what the next paragraph is doing. This way, I will quickly locate the parts of code related to my problem and skip over uninteresting details. Commented Sep 1, 2014 at 11:57
  • 1
    @FlorianF: the traditional response is that variable and function names should indicate roughly what the code is about, and hence let you skim over things that certainly aren't about what you're looking for. I agree with you that this doesn't always succeed, but I don't agree so strongly that I think all code needs to be commented to aid searching or skim-reading. But you're right, that's a case where someone is reading your code (sort of) and legitimately doesn't need to understand it. Commented Sep 1, 2014 at 12:01
  • 2
    @Snowman People could do that with variable names. I have seen code where the variable listOfApples contained a list of Bananas. Someone copied the code processing the list of Apples and adapted it for Bananas without bothering changing the variable names. Commented Sep 1, 2014 at 19:42