Hacker News new | ask | show | jobs
by sidww2 4749 days ago
To be fair, the job of the academia is to do research. Coding is just a means to an end. If on the other hand, you're distributing your code or it's intended as an ongoing project, then good comments and architecture are important (Disclaimer: I'm a PhD student).
1 comments

The job of the engineer is to ship products, not code. (Unless you sell code or maybe library-components)

See, it's easy to ship responsibility on either side, with the exact same line of reasoning.

Usually though that product code will be worked on by many other people. The same is often not true of academic projects.
There's still an opportunity cost to writing documentation. How many other people will work on that code? 2-3? 12? 100? 2000? If it's 2-3 or even a dozen, you're better off explaining in person how it works, while if it's 2000 there better be some persistent written documentation.

It probably also doesn't help that the number of people who look at a given piece of code follows a power law, which means that when you're doing the looking, you are probably looking at a piece of code that many other people have looked at. Everybody remembers the terrible mess that they had to puzzle out without any documentation. Most of the time they don't remember all the little experiments they did that never saw the light of day, where time spent documenting would just be wasted.

If the product you're working on is a long term project of the company, it's likely you'll leave before it's over in which case there will be a future person who'll have to figure out your code. In such a case, documentation is essential as otherwise this person would have to contact you after you've moved onto other projects and may have forgotten the intimate details of the code making things tricky.
That's why you have at least two people work on every part of the code, ideally together, but you could easily arrange a hand-off. Solo-developer projects are bad ideas for other reasons, notably that if you get hit by a truck the company is SOL.