Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Why programmers don’t write documentation

kislayverma.com

Post reply on HN
Print view View original

131–140 of 153 posts

Re: Why programmers don’t write documentation

#131

Post by Ma8ee »

For me the critical part of the text is

> A disorganized pile of classes and methods in code may work – a pile of work of words and paragraphs won’t work. Writing HAS to be clear if it is to be of any use. Code will be accepted (to some extent) as long as it does its job.

This suggests to me that the problem with writing documentation isn't that writing in itself is hard. It is that it is hard to write clearly about badly organised code. So the average programmer can get his disorganised pile to compile and pass the tests, but he can't clearly articulate, in speech or in writing, its organisation.

It's similar to the problem of naming things. If it is hard to find a clear and precise name for a class, it is usually because the purpose of the class isn't clear and precise.

So my suggestion is to write the documentation in advance. If the organisation of the code is very hard to express in plain English, then it is because the organisation of the code isn't very well thought through in the first place, and should therefore be worked on some more. And that is easier to do before a lot of code is written already.

Re: Why programmers don’t write documentation

#132

Post by watwut »

TeMPOraL wrote: post #119
KaiserPro wrote: post #109

Documentation is a skill. Like any skill it takes practice. I have moved to a FAANG and their documentation is downright fucking awful. _everyone_ just writes code, with lots of "clever" bits, and doesn't bother to fucking comment. Not only that because people don't even _comment_ their code, the wiki is a total shit show. Want to know how to use a Queue? tribal knowledge. want to know which DB is best for x? tribal…

> Documentation is a skill. Like any skill it takes practice. The type of documentation you described - code comments and wiki entries - they don't need practice. They only need care. If you know how to write a function that takes Foo and transforms it into Bar under conditions X and Y, you also know how to just append this above it: //! Transform Foo into Bar //! //! Foo must be an X-ing Quux adhering to Y. //! Foo…

These seem too me mostly useless comments. I need comments for things that are not apparently visible. Transforms foo into bar is either clear from params and return types, or should be from name. Likewise, in most cases it is easy to see whether argument changes.

The parts that are difficult to see and difficult to understand are the one that need documentation. They are the ones that happen to be difficult to explain.

Re: Why programmers don’t write documentation

#133

Post by zabzonk »

29athrowaway wrote: post #125
zabzonk wrote: post #42

Earlier quoted context omitted.

Now you have one more problem (several, in fact) - explaining the business and the software to the technical writer. This is so difficult, that in all my long career in software development and management, I never saw any company specifically hire a technical writer, though I have done a lot of technical writing myself, on the side.

The technical writer can be involved in the release management and ask for details that then he can use as a starting point. They can help identify gaps in documentation, outdated documentation, etc. They can take care of the clarity, formatting and distribution. You can create a ticket about documentation and assign it to them. Then, while many developers write excellent documentation... some other developers truly…

About as much could be expected from a throwaway account.

> All of that is a distraction from doing my job.

What job would that be? Do you actually have one?

Re: Why programmers don’t write documentation

#134

Post by watwut »

mattlondon wrote: post #101
hesdeadjim wrote: post #6

I’m in games so the visual element often forces this, but I’ve moved our team to making a lot of video content, both for PRs and for much of our “documentation”. I’ve always preferred reading, and the trend to everything being on YouTube has driven me nuts, but I’m a convert to this method for a few reasons. First, it’s fast. I can sit down and make a deep dive video in 30 minutes and not have to sit around writing a…

With respect, you save time making 30 minute videos, but everyone else then wastes time watching your video looking for info. I prefer it if people just write it down so I can ctrl-f or find it in a web search and get what I need instead of sitting through your videos. For general "welcome to Team X!" onboarding or training though I agree that videos have benefits. But for day to day knowledge and docs I couldn't thi…

I prefer documents too. But the fact is, the choice is between nothing at all and videos.

Re: Why programmers don’t write documentation

#135

Post by eaa »

billytetrud wrote: post #34

Documentation is so important. The problem with documentation is that engineers don't seem to understand it's benefits. I think one reason is that so much of the documentation out there is so poor quality that engineers think documentation can't be good quality.

You are right! You said just what David Parnas keeps saying. People don't know what or how to document because they weren't taught to do it. It's not common knowledge. One has to dig into reading books and papers just to get the idea that it is possible.

Re: Why programmers don’t write documentation

#136

Post by 29athrowaway »

zabzonk wrote: post #133
29athrowaway wrote: post #125

Earlier quoted context omitted.

The technical writer can be involved in the release management and ask for details that then he can use as a starting point. They can help identify gaps in documentation, outdated documentation, etc. They can take care of the clarity, formatting and distribution. You can create a ticket about documentation and assign it to them. Then, while many developers write excellent documentation... some other developers truly…

About as much could be expected from a throwaway account. > All of that is a distraction from doing my job. What job would that be? Do you actually have one?

> About as much could be expected from a throwaway account.

For privacy reasons as this is indexed in search engines and comments cannot be deleted after 1 hour, forever.

> What job would that be? Do you actually have one?

I do, and it's none of your business.

If you want to participate in a community with an expectation of real life identity go have your discussions on Facebook or whatever.

Re: Why programmers don’t write documentation

#137

Post by TeMPOraL »

watwut wrote: post #132
TeMPOraL wrote: post #119

Earlier quoted context omitted.

> Documentation is a skill. Like any skill it takes practice. The type of documentation you described - code comments and wiki entries - they don't need practice. They only need care. If you know how to write a function that takes Foo and transforms it into Bar under conditions X and Y, you also know how to just append this above it: //! Transform Foo into Bar //! //! Foo must be an X-ing Quux adhering to Y. //! Foo…

These seem too me mostly useless comments. I need comments for things that are not apparently visible. Transforms foo into bar is either clear from params and return types, or should be from name. Likewise, in most cases it is easy to see whether argument changes. The parts that are difficult to see and difficult to understand are the one that need documentation. They are the ones that happen to be difficult to expla…

It depends on the language. Perhaps Haskell will not need such comment at all.

In C++, at the very least the preconditions X and Y, as well as the invariant Z, will usually not be apparent from the function signature. Whether the argument is modified? That's usually clear from the use of const... except when it isn't, e.g. because the function is a universal-reference template, or some C compat thing that must use bare pointers because reasons.

In JavaScript, you won't even know Foo, Bar and Quux, unless someone puts it in the function name.

The primary benefit of such comments is to encode enough information that isn't obvious from the signature, that you don't need to read the actual implementation. It's particularly useful if you're using an editor or IDE that can pull signature comments and show them during auto-completion - it saves you from constantly jumping into other places in the codebase, just to verify if you're picking the correct function for the task.

Re: Why programmers don’t write documentation

#138

Post by variaga »

watwut wrote: post #132
TeMPOraL wrote: post #119

Earlier quoted context omitted.

> Documentation is a skill. Like any skill it takes practice. The type of documentation you described - code comments and wiki entries - they don't need practice. They only need care. If you know how to write a function that takes Foo and transforms it into Bar under conditions X and Y, you also know how to just append this above it: //! Transform Foo into Bar //! //! Foo must be an X-ing Quux adhering to Y. //! Foo…

These seem too me mostly useless comments. I need comments for things that are not apparently visible. Transforms foo into bar is either clear from params and return types, or should be from name. Likewise, in most cases it is easy to see whether argument changes. The parts that are difficult to see and difficult to understand are the one that need documentation. They are the ones that happen to be difficult to expla…

What's missing IMO from those example comments (and most automatic documentation) is the "why". I can almost always look at the code to figure out that a function takes a Foo and returns a Bar. What's almost never obvious from the code itself is "why would I want to convert a Foo to a Bar" or "under what circumstances should I use this function instead of something else".

E.g.

  char* strncpy(char *dst, const char *src, size_t n)
and

  size_t strlcpy(char *dst, const char *src, size_t size)
both copy a string from src to dst with a limit on the number of bytes copied. Good comments for would not simply explain what they do and what the arguments/returns represent, but under what circumstances to prefer each variant.

Going with the "6 W's":

"How" (does this code work) and "What" (does this code do) can mostly be explained by the code itself, although comments should be used to clarify anything non-obvious, for instance if you're depending on a side effect or something.

"Where" (should you use this code) and "why" (should you use this code) need to be covered by comments. It is extremely hard to figure those out from the code alone.

"Who" (wrote it) and "when" (was it written) should be in the version control system metadata. Putting those in comments is a good way to ensure the comments are out-of-date/wrong in any long-lived codebase.

Re: Why programmers don’t write documentation

#139

Post by iudqnolq »

yoz wrote: post #97

There are a remarkable number of commenters saying no , documentation isn't hard actually . One question for those commenters: How do you test your documentation? Properly test it, ensuring that it answers many kinds of questions for those who are new to the topic, and who haven't already been working on this project for months? If you're not testing it, then how can you consider it done? Would you do the same with y…

I appreciate languages that at least test code examples, like Rust and (sometimes) Python.

Re: Why programmers don’t write documentation

#140

Post by TeMPOraL »

variaga wrote: post #138
watwut wrote: post #132

Earlier quoted context omitted.

These seem too me mostly useless comments. I need comments for things that are not apparently visible. Transforms foo into bar is either clear from params and return types, or should be from name. Likewise, in most cases it is easy to see whether argument changes. The parts that are difficult to see and difficult to understand are the one that need documentation. They are the ones that happen to be difficult to expla…

What's missing IMO from those example comments (and most automatic documentation) is the "why". I can almost always look at the code to figure out that a function takes a Foo and returns a Bar. What's almost never obvious from the code itself is "why would I want to convert a Foo to a Bar" or "under what circumstances should I use this function instead of something else". E.g. char* strncpy(char *dst, const char *src…

I mostly agree with what you wrote, but then take a look at the man pages for the two functions you mentioned:

https://linux.die.net/man/3/strlcpy

https://linux.die.net/man/3/strncpy

Note how most of the text there is focused on the "How" and "What", because both functions have a bunch of requirements for their arguments that are not expressed in their respective signatures.

Some languages have better tools for expressing these requirements in code. But when they can't be expressed in a way that can be enforced by the compiler, IMO they absolutely need to be mentioned in an interface-level comment (i.e. above function signature), to give users a fighting chance of avoiding bugs.

Also worth noting that the particular constraints around strncpy() and strlcpy() will not be obvious in the implementation either - the programmer trying to make use of these functions would have to study the implementation to notice potential issues. A well-placed comment can save them an expensive context switch here.

Post reply on HN