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

I’d argue if the why isn’t clear from code alone, then it’s the programming language’s or library API’s fault.

Until you have a better language or library, write comments but you should be striving to find better tools.



Which PL features could replace comments in natural language in your opinion?


LINQ in C# makes code very declarative, not only reducing the line count by half but also making it obvious what the code does. Code like persons.Where(x=>x.age>21).OrderBy(x=>x.Name).ToList(); doesn’t need a comment to spell out what it does, but imperative code might.

Being able to easily create types as needed gives not only compiler guarantees but also communicates exactly what sort of “id” or “name” you’re dealing with.

Generics separate orthogonal parts of logic, e.g. a List vs domain object. I remember the days when the domain objects would contain the “next” pointer. More generally any ability to separate aspects is hugely helpful. Eg: list<lazy<person>> is a lot easier to read than baking it all that in one object. Once done, you don’t have to have a section of code inside person that says “instantiate these fields lazily for performance”.


You’re asking the wrong question.

Better question: “What feature am I missing from my current PL or API that would mean I didn’t need this comment/documentation?”

Then strive to get that built.

For example a type system removes the need for an entire kind of method comment.

DSLs are excellent at this. Lombok removes the need for an entire kind of class comment.

Convention over configuration is great at this. Rails routes removes the need for an entire kind of comment.

Moving optimization’s into the compiler are good for this. Removing the need for an entire kind of comment.

Rust’s borrow checker removes the need for an entire kind of documentation around concurrency.

Every time a PL or library gets more advanced/ergonomic it removes the need for an entire kind of documentation.

Why shouldn’t we strive to take this to the limit, making better and better PLs and libraries till we need 0 documentation?




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

Search: