[nsgoetz]

I took an OS class in college where either a TA or professor would read every line of C code in the OS you turned in. They required every function to have a doxygen style doctrings. It was also a partner based course. Writing those docstrings before implementing the functions not only helped them be more useful, but also helped my partner and I coordinate on features/interfaces before they were done. I think documentation in general is highly underrated.

[wck0]

I forget where I saw this, but it struck me as very good advice: Don't document your code, code your documentation.

[cbcoutinho]

Sounds like literate programming, popularized by Donald Knuth

[iamdave]

I like that.

So many times I've looked at a peer's code and had a hard time reconciling what the comments and wiki articles said with what their code was attempting to do.

This mindset is probably a godsend to QA teams.

[madhadron]

My father was convinced that Quark XPress was written that way: once they had the core functionality figured out, they wrote the manual, then implemented it.

[bitL]

The thing is - this is interesting because nobody is doing it anymore. Once everybody starts doing it, i.e. literally "human politics" gets directly involved on all levels of development, everybody would try to escape this style to get some development freedom for themselves to stay sane.

[justizin]

this is pretty much de facto in python, and though not as widely used as i'd like, there is a testing framework called doctest which allows you to write tests in the documentation.

so for a given method or class, you have a couplefew paragraphs which explain how to use it, with invocations that are run as part of the test suite.

sometimes there end up being too much acrobatics for this to be as useful as i'd like, but the basic idea is really neat, IMO.

[roblabla]

Also a feature of Rust: Every example in your docs are tested with your unit tests (unless you explicitly turn it off for a specific example). It's also a useful way to check that you didn't change your API by mistake, or generally make sure your doc is up to date.

[crdoconnor]

Doctest exhibits this idea but it only really works for small, self contained utility functions - e.g. slugify a string, round a number to 3 decimal places, etc.

[slededit]

Doxygen should never be your sole source of documentation although a lot of projects use it that way. It does not communicate the design philosophy behind the code, so while it will answer whether you can use an API a certain way it doesn't answer if it was the intended use. This becomes important because once you step outside the programmers intent things are less likely to work and will be more brittle.

If you are a public library it also results in the infuriating situation of knowing an API will do what you want but not knowing how to get a parameter or class it requires.

[ausjke]

sorry, what do you mean by 'doxygen style docstring', and is the docstring still doc, or variable/function-names for the code?

[nsgoetz]

doxygen is tool to programmatically generate documentation from properly formatted comments. If you use python, it is very similar to pydoc. We never actually used the generated documentation but basically used the format as a style guide. For functions it looks like:

  /** @brief Prints character ch with the specified color
   *         at position (row, col).
   *
   *  If any argument is invalid, the function has no effect.
   *
   *  @param row The row in which to display the character.
   *  @param col The column in which to display the character.
   *  @param ch The character to display.
   *  @param color The color to use to display the character.
   *  @return Void.
   */
  void draw_char(int row, int col, int ch, int color);

Here is the class's guide to doxygen https://www.cs.cmu.edu/~410/doc/doxygen.html