Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

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

haskell.org

Post reply on HN
Print view View original

161–170 of 198 posts

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

#161

Post by krzrak »

krzrak wrote: post #139
seanmcdirmid wrote: post #59

Earlier quoted context omitted.

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?

> But you have to ship in 4 weeks, so why not just get something working first? Of course, this sometimes happens, but it shouldn't be encouraged. This way you are creating technical debt, which will be very expensive to pay off.

> At what point is simple simple enough?

It's hard to explain. You know it by experience.

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

#162

Post by seanmcdirmid »

krzrak wrote: post #139
seanmcdirmid wrote: post #59

Earlier quoted context omitted.

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?

> But you have to ship in 4 weeks, so why not just get something working first? Of course, this sometimes happens, but it shouldn't be encouraged. This way you are creating technical debt, which will be very expensive to pay off.

I actually work on problems that haven't been solved previously (or why not just get a dev to do it rather than a researcher). I get offended when some dev who writes web apps connecting to databases all the time says "all code should be simple." They really don't have a clue.

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

#163

Post by transfire »

It is easy to spot (most of) the experienced coders from the newbie coders. Any programmer who has written his salt worth of code knows that comments can save your ass. Come back to some code ten years later and you can sit there staring at a bit of code no bigger than your thumb wondering what the hell it does and often it doesn't become clear until you shove some test samples down its interface and see the result. Whereas a simple comment is all it would have taken to clear it up from the start. People who argue that comments can get out of whack with code, well, of course they can, but that's no excuse. That's just a failure on the programmers part to always update comments when the code changes.

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

#164

Post by otikik »

kelvin0 wrote: post #156
otikik wrote: post #152

Earlier quoted context omitted.

Well that is ... sad. I have not been around for 30+ years and I see good code on a weekly basis. Maybe you should consider changing something in your environment. I assure you it is possible.

Maybe he 'sees' bad code that you would consider 'good' code. This can be a bit subjective, and also he has much more experience than you ...

Maybe. It's still sad.

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

#165

Post by otikik »

reitanqild wrote: post #106
seanmcdirmid wrote: post #63

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.

Disagree. Reason: In Software Archeology (a.k.a. maintaining legacy code) you are often happy to get any kind of clue as to what went on inside someones head. Maybe they saw an edge case? Of course you should write self-documenting code with variables and function names that explains most of it but when you either have to 1. factor out a new function do_this_to_fix_that_weird_thing(weird state) or 2. have to add a li…

I will take 3

3. fix_bug_that_occurs_even_when_api_docs_say_otherwise(weird)

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

#166

Post by vamega »

tveita wrote: post #71
icebraining wrote: post #27

Earlier quoted context omitted.

Well, this is Haskell we're talking about. Between the name, type signature and the fact that most functions are pure (so, no side-effects to describe), it's often obvious what they do.

Like ( ) :: Monoid m => m -> m -> m (^?) :: s -> Getting (First a) s a -> Maybe a As a Haskell beginner I didn't find it to be a particularly self-documenting language. Between the use of custom operators and point-free style you can write a lot of code without naming anything to give a hint about what you're doing.

So as another Haskell beginner, let me take a stab at the first one.

  * Return the first parameter
  * Return the second parameter
  * Perform param1 `mappend` param2
  * Perform param1 `mappend` param2
  * Return the mempty value for the Monoid m
The first two are unlikely to be correct, since if all they were doing was returning a particular parameter, then there is no reason to have the Monoid type constraint. The last one similarly makes no sense, since it's a function that is identical to `mempty` irrespective of it's parameters.

The order of operations however should be documented. I'm almost certain that the implementation is the third function, but a one line comment stating that could possibly be useful.

All of my above reasoning was predicated on an understanding of Monoids. So while I'm not sure the right thing to document is the function, I do think an explanation of `Monoids` should be documented in `Data.Monoid`.

PS - Where is that first function defined? I've used a similar operator defined in XMonad, but if I remember right that was defined over Arrows. Also is that second function from Data.Lens?

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

#167

Post by dllthomas »

vamega wrote: post #166
tveita wrote: post #71

Earlier quoted context omitted.

Like ( ) :: Monoid m => m -> m -> m (^?) :: s -> Getting (First a) s a -> Maybe a As a Haskell beginner I didn't find it to be a particularly self-documenting language. Between the use of custom operators and point-free style you can write a lot of code without naming anything to give a hint about what you're doing.

So as another Haskell beginner, let me take a stab at the first one. * Return the first parameter * Return the second parameter * Perform param1 `mappend` param2 * Perform param1 `mappend` param2 * Return the mempty value for the Monoid m The first two are unlikely to be correct, since if all they were doing was returning a particular parameter, then there is no reason to have the Monoid type constraint. The last one…

I assume line 4 was meant to be:

    * Perform param2 `mappend` param1
I'd be a little surprised if it was the third option, simply because that's already spelled . Hoogle doesn't turn up a definition with that signature, though.

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

#168

Post by callum85 »

It seems like no one here shares my opinion on this: I really like comments, even if they just restate, in English, what the code does. I don't think that's pointless. There is big value in it. I can scan and mentally process English sentences much faster than code. With a heavily commented file you can just skim through the comments until you locate the part you need to work on (then slow down and read the code around it and edit it).

Look at the Backbone.js annotated source [1] (the stuff on the left is just the comments pulled out from the original source JS). The comments make it much, much quicker to grasp what's going on, even though many of them just state exactly what the corresponding code does, which according to the Haskell docs' advice is pointless and to be avoided.

[1] http://backbonejs.org/docs/backbone.html

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

#170

Post by tbrownaw »

augustl wrote: post #66
rotten wrote: post #61

Of course everyone thinks they always write good clean code and therefore don't need comments to elaborate on what the heck is going on. Unfortunately, having been doing this trade for 30+ years, I've found most people write crappy code in a hurry to try to hit some deadline based on incomplete requirements and confusing business rules. A few precious comments stuck in there can help the next guy, months or years lat…

I wonder where the idea comes from that people that write code that's hard to understand, will write comments that are easy to understand.

    -- NOTE
    -- This is called by the database-level DDL trigger.
    -- Do not drop it. Do not break it.
We don't have a dev/qa environment, and tend to be a bit... lax about change management. There are a few pieces of code that this is particularly unsuitable for.

    function f_soundex (p_in varchar2) return varchar2
    is
    -- [name of specific source file from one of our other systems]
    -- If the first (kept) letter has the same code as the following letter,
    -- a proper Soundex ignores that following letter. The [other system] soundex
    -- keeps it.
Sometimes it is necessary to do weird things for compatibility reasons.

    // See http://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=98335
    // Apparently, DestroyHandle doesn't get called properly when a control is disposed. Since this
    // makes Invoke() hang, we have to fix it.
Sometimes external libraries/frameworks have bugs to work around.

    /* Don't let things scope to the repeat block. Even when they aren't used, they
       make the end statement slow. read-record.i has strong scoping for the data
       tables, and everything else is lifted to procedure scope. */
Sometimes there are performance reasons for doing things in a particular slightly odd manner. Sometimes there are correctness reasons (as with a 9-line comment earlier in the same program as this last example).
Post reply on HN