Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

Documentation is useful, when done well. The code is always the authority, and there are very many ways the correct logic can be constructed. How it is constructed is the difference between good enough and excellent.

And getting "compromise on timelines" is a most sublime political art. It requires the combination of both a humble, competent manager and an established, successful engineer worthy of trust.

Congratulations on your success on those two varied fronts!



I think it depends on who the documentation is intended for. I often let public facing documentation be the source of truth for expected behavior unless it's infeasible to coerce the system to that behavior. If the latter does occur, the documentation gets updated.

If the question is what does the software actually do, then of course the code, toolchain, and runtime are the authority.


Good point. I was only speaking to targeting other developers.


It needs to answer the "why" question most IMO. I can read code and see "how" and perhaps guess "what" but the "why" is missing.

It also doesn't have to be that detailed - just a one line comment at the top of a file saying why it's there and what for can make an immense difference to the time it takes to understand code.

Class comments are great too if they have in them everything that's NOT in a ChatGPT summary :-). i.e. I can paste code into ChatGPT myself to get a summary if I really wanted to so I don't need that - but I need all the things it doesn't tell you which is basically why the class exists and what it's intended for.

The lower down the hierarchy it goes the less comments matter IMO.


Thank you! I am indeed very fortunate to have a great manager.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: