Live data from Hacker News

I've never seen a language's style guide recommend avoiding comments before

haskell.org

91–100 of 198 posts

Re: I've never seen a language's style guide recommend avoiding comments before

#91
The thing with comments is: You should add them for people that don't want to read your code line by line.

I don't want to run my internal compiler in my head when i'm reading your code, so you better make sure there's at least a docblock above every function that describes in 2 sentences what it does so I can get a global overview of what the heck this file is doing.

People that suggest that 'the code is the documentation' are always forgetting that reading code is way more taxing on the brain than reading english.

Re: I've never seen a language's style guide recommend avoiding comments before

#92
Here's a small function from a real world module used in a Haskell web backend. It decides whether a "work unit" is appropriate to pick from a queue. The first iteration was a pretty complex piece of code. When I refactor, I often think "this is unclear and should be commented," but I've learned instead to think "this is unclear and should be factored out and given a significant name." So I ended up with this:

    shouldPickWorkUnit :: (ImportId, WorkUnit) -> STM Bool
    shouldPickWorkUnit (k, u) =
      case hostNameFor url of
        Nothing       -> return True -- Invalid URLs are fast to process.
        Just hostName ->
          takeWorkThat'sAlreadyDone 
            (don'tTakeSomeoneElse'sWork 
              don'tExceedTheRateLimitFor hostName)
This way, the domain logic is legible from the actual code, which strikes me as almost always better than having tricky code with comments. Trying for this also encourages "domain-driven abstraction," and this is one of Haskell's greatest strengths.

In fact, the remaining comment can be factored away too:

    shouldPickWorkUnit :: (ImportId, WorkUnit) -> STM Bool
    shouldPickWorkUnit (k, u) =
      takeWorkWithInvalidUrl 
        (takeWorkThat'sAlreadyDone 
          (don'tTakeSomeoneElse'sWork 
            don'tExceedTheRateLimitFor hostName))
Advice like "avoid comments" needs to be taken as a calling for actually spending time and effort to write obvious code, and for using appropriate abstractions!

Re: I've never seen a language's style guide recommend avoiding comments before

#93
post #43

Hmm. This is just one guy's style guide on the public wiki. http://www.haskell.org/haskellwiki/index.php?title=Commentin... It isn't official in any sense.

Right, also, it doesn't actually say avoid comments, it just gives examples of where it's best to try and find an alternative.

In the bitcoinj code style guide there is a big section on comments that gives positive examples as well as negative examples:

http://bitcoinj.github.io/coding-conventions

Re: I've never seen a language's style guide recommend avoiding comments before

#94
post #51

Earlier quoted context omitted.

There is no such complex function that can't be decomposed to bunch of simple(r) functions.

Often only with a deep understanding of the complex problem to understand its simplicity. But you have to ship in 4 weeks, so why not just get something working first?

Because simpler code usually leads to less bugs, which is faster and cheaper than complex, buggy code.

Re: I've never seen a language's style guide recommend avoiding comments before

#95
post #83

Earlier quoted context omitted.

But all too often, people who write hideous code sprinkle it with comments that merely explain what is done, at the lowest level.

Yes. The industry is full of hacks. I don't see how that's a problem with comments though. They're going to write hideous code with or without comments.

The problem is that comments visually bloat the code and make it harder to understand. Bad code with useless comments is worse than bad code with no comments. And that's not even counting comments that are out of date and misleading...

Re: I've never seen a language's style guide recommend avoiding comments before

#96
I'd say the language design and language ecosystem has a LOT to do with it as well. Here are a few lines of Java that I just had to write about 10 minutes ago.

  PendingResult pending = Wearable.MessageApi.sendMessage(mGoogleApiClient, mWearableNode.getId(), path, data);
  pending.setResultCallback(new ResultCallback() {
      @Override
      public void onResult(MessageApi.SendMessageResult result) {
          ....
      }
  }
Okay, now suppose this were a Python-based API instead? Perhaps it could be something like this, after some relevant initialisation:

  wearable.sendmessage(mywearable, path, data)
  
  @wearable.onresult
  def onresult(result):
    ...
Tell me which one is more in need of commenting.

Re: I've never seen a language's style guide recommend avoiding comments before

#97
I see rubbish like this in PHP (and Java) code all the time:

    /**
     * Frobnicates a foobar
     * 
     * @param Foobar $foobar The foobar to be frobnicated
     * @param int $intensity The intensity with which the foobar will
     *    be frobnicated (defaults to 4)
     * @return mixed The result of frobnicating a foobar
     */
    function foobar_frobnicate(Foobar $foobar, $intensity=5)
    {
        // frobnicates the foobar
        return $foobar->frobnicate($intensity);
    }
It's utterly ridiculous.

Pretty sure I've been guilty of this in the past, too. As I recall, the documentor tools make a lot of noise if you don't supply wasteful and irrelevant values for every single little thing even if it's blindingly obvious from the symbol, context or idiom what it means and what it does.

Re: I've never seen a language's style guide recommend avoiding comments before

#98

Earlier quoted context omitted.

> Comments cost essentially nothing to add to your code and can save it from an early death and complete refactoring by the next guy who comes along. Whatever their benefits are, this is not true at all. Comments are expensive to write and maintain. They are VERY VERY expensive to maintain because there is no automated way to test them.

Forgive my ignorance, but why and how would you test a comment? They don't do anything, there is no instruction for the machine to understand or run.

The comments are meant to be read and used to understand code. So you must test them like any other artifact to ensure that they are a net positive and not a net negative. Programmers make mistakes, which hopefully fail a test or at least cause a crash. Because comments can't be executed, neither of those will happen; they have to be verified manually

Re: I've never seen a language's style guide recommend avoiding comments before

#99
post #75

Earlier quoted context omitted.

Then you will read the comment that says to do one thing but the program will do a completely other thing. I don't see any problem, do you?

That's why good comments are about explaining WHY you're doing something, or HOW to use the code, and possibly making the code itself clearer but only if there's no way to do that by introducing better variable and method naming. Comments are highly valuable but like any tool they can be abused, or done in such a way that they don't make things better.

The point is that comments can become out of date, and there's no automated way to enforce they stay up to date.

Re: I've never seen a language's style guide recommend avoiding comments before

#100
A partial list of problems

Assume someone who can't write clear code can write clear comments. Also search and replace clear with "readable" "literate" "concise" and last but not least, "correct"

Assume a programmer has full authority over all 3rd party, supplier and customer APIs, interdepartmental processes, and all business logic, management selected fad technologies, such that its logically impossible to be unable to always factor out weird confusing stuff resulting in clear code / clear comments. My program is the world and none have dominion over any of the rest of it and any other conception of reality is wrong. (And edited to add I've gotten involved in some weird "EE" stuff and like it or not, the world itself is plain old weird and illogical sometimes and if you don't like that, a computer programmer can't fix it, only a physicist, or maybe a diety. This isn't a big problem in the world of CRUD apps but it does happen)

Assume comments only exist as a inspirational descriptional prose tool. Sometimes I use them as placeholders for something I know belongs there but either I or the business are not ready. Sometimes I use them as a cheatsheet because I'm personally really uncomfortable. Sometimes I use them as an outline more like names on a map to orient myself than a travelogue.

Assume all programmers fit the management ideal of identical replacable cogs. "How could someone work here without knowing by heart how to convert dBmW into volts or the difference between S21 and S12 microwave scattering parameters, so I have no need to comment this, but I've never actually used this corner of matrix math while employed before so I'll make one of those laughable comments that is a simple linear translation just to help me keep my head on straight.

Assume comments go thru the same code review process as code. If a comment in file A tangentially relates to function Q in file B, and you modify function Q, your code review process will probably examine file B and the comments in it, but how do you ensure file A gets modified? This is especially bad with those "because" style comments. (edited to add, at least date your comments?)

Assume no metrics exist WRT comments to be gamed. Your continued employment and possible promotion exist because of a content free meaningless metric number, perhaps lines of comments. Ask a professional to generate a number, you'll get a nice number, but unprofessional work. Ask a professional to do professional work, and you get professional results and who cares what the number is. That requires a high caliber of management, usually unavailable. Even worse a low caliber of management, the kind most likely to demand adherence to meaningless metrics, is also exactly the type least likely to successfully evaluate the professionalism of the code so they don't end up with good code. So you get meaningless metrics resulting in meaningless comments right next to bad code, if you enforce metrics.

Assume there exists a silver bullet for comments, just like this months silver bullet fad for code also fixes all problems.

(edited to add) Assume there's one human language. I worked at a place where outsourcing and H1B took complete control over corporate IT such that code comments and even some internal documents were no longer written in English. This makes comments rather hard to follow when engineering tries to cooperate with IT. So... I'd love to follow your detailed internal process for dynamic DNS for my spectrum analyzer, but you guys don't use English and we don't use your India language, so...

Post reply on HN