6 ms·

> @param title > @param author > @param tracks > @param durationInMinutes May the params be null (title, author) or <= 0 (tracks, durationInMinutes)? What h

> @param title > @param author > @param tracks > @param durationInMinutes May the params be null (title, author) or <= 0 (tracks, durationInMinutes)? What happens in such cases? Is an Exception thrown? Which? What exactly is the result of addCD()? Which related methods are available? ... Yep, avoid bad comments, provide informative comments!

mbrock 13y ago
In systems grown over many years and by many developers, comments about such things are nearly worthless, because they can't be trusted. I wouldn't be surprised to see a comment saying "title cannot be null" right above code that explicitly permits null. A comment that lists which exceptions can be thrown is highly suspect, I would probably delete that just to avoid confusion, and make sure that it's obvious from the code instead.
- ExpiredLink 13y ago
  > comments about such things are nearly worthless The Java ecosystem lives on such comments. I wouldn't use a Java API without "Javadoc" documentation.
  - mbrock 13y ago
    I don't endorse this way of developing software. It's profoundly bad -- in a way that comments can't fix.
- MaulingMonkey 13y ago
  When code has been poorly refactored (I'd count "documentation/comments weren't updated") I find knowing the original intent behind classes and methods to be useful in understanding their mutated design, and how it was arrived at. Further, handling of the edge cases may have changed, but many of those changes may be bugs in the code to be fixed rather than intentional design changes to be re-documented. When fishing for the cause of a crash, said comment can help verify the existence of a bug, even if it's not the bug you're looking into. They can also guide the fixing of that bug. This variable shouldn't be null: is that the fault of the callee for not providing a fallback? the caller for violating function preconditions? caller of caller for the same? another class that had it's invariants violated without asserting?
ajanuary 13y ago
Those sorts of things are useful, but mainly on API edges. They also tend to get outdated pretty quickly in code with even moderate churn. It would be interesting to be able to link assertions in a method doc with a test, so that the doc export process/IDE will complain if the test ever gets removed (because the API changed).
tome 13y ago
Types are typically better documentation than comments: addCD :: CDCollection -> String -> Maybe String -> NonNegativeInt -> NonNegativeDouble -> Either FailureType CDCollection This answers all your questions except for "Which related methods are available?" and the anwsers are checked for correctness at compile time!
- ExpiredLink 13y ago
  You could just write a monad instead.

mbrock 13y ago

In systems grown over many years and by many developers, comments about such things are nearly worthless, because they can't be trusted. I wouldn't be surprised to see a comment saying "title cannot be null" right above code that explicitly permits null. A comment that lists which exceptions can be thrown is highly suspect, I would probably delete that just to avoid confusion, and make sure that it's obvious from the code instead.

ExpiredLink 13y ago
> comments about such things are nearly worthless The Java ecosystem lives on such comments. I wouldn't use a Java API without "Javadoc" documentation.
- mbrock 13y ago
  I don't endorse this way of developing software. It's profoundly bad -- in a way that comments can't fix.
MaulingMonkey 13y ago
When code has been poorly refactored (I'd count "documentation/comments weren't updated") I find knowing the original intent behind classes and methods to be useful in understanding their mutated design, and how it was arrived at. Further, handling of the edge cases may have changed, but many of those changes may be bugs in the code to be fixed rather than intentional design changes to be re-documented. When fishing for the cause of a crash, said comment can help verify the existence of a bug, even if it's not the bug you're looking into. They can also guide the fixing of that bug. This variable shouldn't be null: is that the fault of the callee for not providing a fallback? the caller for violating function preconditions? caller of caller for the same? another class that had it's invariants violated without asserting?

ajanuary 13y ago

Those sorts of things are useful, but mainly on API edges. They also tend to get outdated pretty quickly in code with even moderate churn. It would be interesting to be able to link assertions in a method doc with a test, so that the doc export process/IDE will complain if the test ever gets removed (because the API changed).

tome 13y ago

Types are typically better documentation than comments: addCD :: CDCollection -> String -> Maybe String -> NonNegativeInt -> NonNegativeDouble -> Either FailureType CDCollection This answers all your questions except for "Which related methods are available?" and the anwsers are checked for correctness at compile time!

ExpiredLink 13y ago
You could just write a monad instead.