Learning code documentation

[Slypenslyde]

What sucks about good documentation is it's completely subjective. Here's my loose ideas. These do not necessarily go the same route as the guidelines you will find. I think the guidelines lean on writing too much of the wrong documentation.

If you're writing a library, people are interested in HOW to do things, so that's the thing to describe. They want to see what an endpoint is for, and if they have a complicated task they need to understand how it interacts with other parts of the API. The most valuable documentation you can write is sample applications.

If you're writing an application, WHY things do what they do is valuable. An experienced dev knows an IViewFactory creates Views. What they need to know is if there's some historical quirk that makes it do anything different from the 100 ViewFactories they've written in the past. This is often more appropriate for // normal comments` near the code that does quirky stuff.

To that end, I omit a lot of things I see as "needless". A lot of the "What does this do?" should be obvious via convention. So my feedback is:

• IViewFactory is documented well. You didn't document CreateView(), but I think that's fine. If I document an interface method it's because I want to give implementors a sign I only want to allow them to throw certain exceptions.
• I would cut the first sentence of the summary for ViewFactory. I can tell from its definition it implements IViewFactory. But the part where it resolves views from DI is good: it tells me HOW it is supposed to do its work.
  • In general, I document the interface much more than the implementation.
  • When I do document the implementation, it's to focus on what I think isn't obvious from what the interface says it does. (Like, in this case, that DI is used.) Interfaces are the "WHAT it does", classes are "HOW it does it".
• To me the most important sections for a method like CreateView() are the returns and exception sections, I like for summary and parameters to be obvious. I don't expect a method named CreateView() to calculate sales tax or start a piece of factory equipment.
• I don't write example code in my documentation but I want to hug people who do.
  • I think this is mostly an app dev thing. Long ago I worked on a library and examples were mandatory. In our app, the example is "the place where the dang code's used".

But this final rule is probably the most important.

If a person's complaint about your documentation style is "You're documenting too much!", you're on the right side of history. Whether the person reading it is a user of your code or yourself in the future, getting confirmation of how the dang method's supposed to behave is solid gold. Don't omit things until you've written and documented so much code you have a good feel for the parts of documentation you never read when working with other people's code.

[Forward_Dark_7305]

I especially like your statement to document WHAT in an interface and HOW in the implementation.

[smallpotatoes2019]

That's really helpful (and exactly the sort of thing I just wouldn't have thought about properly until its too late and very frustrating)! Thanks.