Whole open-source in just one sentence:
You not only can read and modify the source code, but also have to, in order to understand what it does and how to make it do what you want, since by default it won't.

Follow

is more important than the code. — Apparently most developers think the opposite way.

If you can't supply additional and useful to humans information for your code, in quantity as much or more than the code itself, you probably have only a very vague idea of what you're ever doing. — A monkey, basically.

@amiloradovsky If you want other people to use your stuff, yes, otherwise, no.

For personal projects, as long as you know how to use it, no documentation is needed.

@sheogorath I'm forgetting how to use my own stuff after a month, not to mention years…

@amiloradovsky I don't know if it's your current mood, my current mood, or combination of both, but I feel insulted reading this. You're postulating something without any hint at why you hold that opinion. Even a rant about a few wasted hours would be better than no justification at all.

@minoru Are you a person who writes sources with obscure contracted identifiers and without any useful comments, and then doesn't bother to write any documentation as long as the program works as you roughly intended? — If so, you should be offended, otherwise you shouldn't.

@amiloradovsky I don't see how these conditions follow from "additional and useful information for your code, in quantity as much or more than the code itself".

Obscurity, unacceptable name shortening, usefulness of comments are all relative and depend on reader's domain knowledge—things useful to experts might still be obscure to a novice reader.

I don't necessarily defend the project that made you toot about this, but be mindful of the fact that this isn't a black-and-white issue.

@amiloradovsky I also don't think that amount of documentation depends on knowing what you're doing.

If you know what you're doing, you may not write docs because it's all in your head already.

If you don't know what you're doing, you may not write docs because it's a waste of time as you're half-exploring and might rewrite everything tomorrow.

People only write docs when they have a use for them, like attracting users and contributors, and aiding their own memory.

@minoru My point was that documentation is primary: you first fix an idea for yourself and for other human readers, and only then turn it into a machine-readable code. If you change your mind about certain details, you first update the human-readable "declaration" of your intent, then the code, not vice versa.

@minoru P.S. "If you know what you're doing, you may not write docs because it's all in your head already." — The memory is volatile. My clear vision of today will fade tomorrow. And other humans aren't telepathic. If you want to exchange an ideas with them, you first have to establish a common language. That's why writing things down is important.

@amiloradovsky If we're talking of user docs, I agree. I first saw it in a screencast by Joey Hess, where he writes a paragraph for the man page first and only then implements the option.

For API docs, I disagree. There, I'd go more with "hints" than "docs": mention how this particular class is part of a set of classes, or how a method affects the system. These "hints" should supply high-level vision rather than minutae already embedded in the code. Synergy, not duplication.

@minoru Documentation, generated from the sources, e.g. extracted from the comments, is only more useful than the source code itself due to a possibly better presentation.
The hierarchy I propose is this:
- Design/architecture overview, (white)papers, only for humans.
- Lots of comments in the sources, to generate the API doc. Also for humans. Take at least half the space.
- Machine-readable code: clarifies minor implementation details for the machine, or curious humans interested in that depth.

@amiloradovsky I have two observations about this.

1. This hierarchy leads to a lot of duplication, because the same things will be said in prose many, many times. On one hand, I see how it's a good thing—it makes it harder for a novice to miss some important aspect. OTOH, the cost of updating all of this skyrockets.

This is a good ideal for a library that stabilized and reached maturity, but for something that's still in any sort of development, this amount of docs is a drag.

@amiloradovsky Actually, there won't be a second observation. I wanted to pick on your last point and say that machines can't understand docs yet, so code can't just "clarify minor implementation details". But then I tried to look at it from "docs paramount" perspective you suggest, and yeah, then it seems logical to view code as something too low-level to bother yourself with.

@minoru I actually meant some kind of literate programming: as in an old Fortran or Ada program, where the comments constitute most of the source code, and, when you're reading it, you're mostly reading the "comments", which are sometimes interrupted by the actual code for the translation.
Yes, maintaining the design documentation first may cost some time. But the lack of it may cost even more…
I actually don't know what else to say here: paper, specification, implementation — the correct order.

@amiloradovsky I don't have any experience with either of those languages, but I can't help but notice that both are the older ones. I expect Fortran code to be pretty dense since the language was literally named after "formula translation". Maybe literal programming made more sense there because the code itself was so devoid of useful hints?

Modern languages let you write much more self-descriptive code. Wouldn't that relax demand for docs a bit?

@minoru
Yes, that Fortran code I saw was very dense: one or two capital letters per identifier… All of those identifiers were properly described in the comments though.
And, yes, modern languages have such features as e.g. doc. strings, but only few languages: Lisp dialects, to be specific. Plus, all sorts of "self-documentation".
But what I was implying initially is that "nobody" uses those: all I see in the sources is just some obscure short names…
IDK how else to describe it, just wrong.

Sign in to participate in the conversation
Functional Café

functional.cafe is an instance for people interested in functional programming and languages.