Four kinds of documentation

Re:Four kinds of documentation by protomikron on Friday October 18, 2019 @08:06AM (#21290608)

Yes.

Now if you use human language to document your functions (methods) that is not a problem, but too often I see something like:

    public class BookStore {
        ...
        
        /**
        * @param book The book.
        * @return The price.
        */
        public static float getPrice(Book book) {
            return book.price()
        }
    }

No shit sherlock! I admit that this is a contrived example, but you get my point.

[ Parent | on HN ]

Re:Four kinds of documentation by noxToken on Friday October 18, 2019 @09:32AM (#21291191)

> No shit sherlock! I admit that this is a contrived example, but you get my point.

Not a contrived example. There are an absurd amount of libraries that do this and call it documentation. There will be a nice, tidy example of how to use the library with a toy example. That's fine. The intro probably doesn't need to go that deep. Then I move to the technical documentation or API, and that's what they have to offer.

[ Parent | on HN ]

Re:Four kinds of documentation by Consultant32452 on Friday October 18, 2019 @09:05AM (#21291018)

I've written MANY javadocs like this, and I agree they are useless. They are derived from draconian build processes that fail builds when there's not a javadoc present. So for trivial methods like setters and getters this is the kind of comment/javadoc you get from me.

Of course, the other side of this coin is that without these draconian build processes I probably wouldn't write the useful kinds of javadocs I write for significant methods.

[ Parent | on HN ]

Re:Four kinds of documentation by acidburnNSA on Friday October 18, 2019 @08:41AM (#21290863)

Yeah, I was coming to say it can be done right, and that's your point too. If you spend the time to put what a thing does, why it does it, and how it does it, with meaningful hyperlinks to related things, then the auto-collected docs can be really slick.

Maybe "auto-collected" is a better term for this than "auto-generated". I agree that auto-generated docs almost by definition don't add much. But if you go in and write narrative and have it get nicely collected into a slick hyperlinked webpage by things like doxygen and Sphinx, then that's great.

[ Parent | on HN ]

Re:Four kinds of documentation by harimau777 on Friday October 18, 2019 @08:57AM (#21290951)

It seems to me that the issue with auto-collected code is that, if done well, it captures the behavior of the code itself. However, it doesn't capture the specification of how the system should work (as opposed to just how it does work) or the higher level design and strategy of the system.

[ Parent | on HN ]

Re:Four kinds of documentation by acidburnNSA on Friday October 18, 2019 @09:05AM (#21291022)

I agree with that too. There needs to be a lot of pure narrative in addition to the auto-collected API Docs. My big project has User Guide (with intro, vision, tutorials and how-tos), Developer guide (with architecture description, requirements specs, implementation overview) and then auto-collected API docs with all the details of how it's currently implemented. In the "notes" admonitions throughout the API docs, there's a some historical information and description of why it is the way it is and how it should ideally be (as appropriate). This feel like it works pretty well. Then again, I wrote a lot of it so I'm biased.

There should be a roadmap somewhere as well, possibly in a Wiki or the developer docs.

[ Parent | on HN ]

Re:Four kinds of documentation by the_af on Friday October 18, 2019 @09:15AM (#21291075)

It's not a contrived example. I see it all the time in Java codebases, and it drives me mad. I always flag it in code reviews and demand an explanation: "what purpose does this comment serve? What would be unclear if we removed it?".

[ Parent | on HN ]

Re:Four kinds of documentation by Karliss on Friday October 18, 2019 @08:50AM (#21290925)

There is also "@param p price". How about not giving argument single letter name so that you don't have to explain it in comment.

[ Parent | on HN ]

Re:Four kinds of documentation by marcosdumay on Friday October 18, 2019 @04:46PM (#21294937)

That comment says the code author actively stopped to think about the function and didn't find anything worth noticing about it.

It is a completely different situation from the lack of such a comment, that implies that the author didn't stop to consider the function, and you can find any kind of strange things when calling it.

[ Parent | on HN ]

Re:Four kinds of documentation by tomcam on Friday October 18, 2019 @03:13PM (#21294238)

My favorite by far is

    y++; // Bump y

Instead of

    y++; // Do we need error checking for top of y axis?

[ Parent | on HN ]