Hacker News new | past | comments | ask | show | jobs | submit login

Isn't your example a perfect case of the comments only being necessary because the code is somehow flawed?



From the comment, it sounds like the code is doing a reasonable thing dealing with a complex problem. The complexity of the problem deserves documentation.


Code being somehow flawed and reasonable are not mutually exclusive. It wasn't stated what the actual problem was the code was solving, so I can't say whether it was complex.

The code needed comments because it crossed layers – in general a sign of bad code. So the idea of "if your code needs comments, there's probably something wrong with it" definitely holds.

Sometimes you need not to do bad things to handle a bad situation (e.g. handling a third party embedded & unfixable system working against the spec), but that does not invalidate the fact that comments are an indicator of "somehow flawed code".


I understand what you are saying but personally I'd rather focus on understanding the codebase rather than on grading it. In this context, I often find comments very helpful, especially the "why" comments.


It had to cross layers, because the original implementation was flawed. The $vendor had designed the their protocol stack well, but implemented it against the very spec they wrote – for example, the outer protocol frame length field did not take into account character escape codes which were a property of the inner protocol. Instead of a protocol stack, the escaping has to be handled with a multi-layer state machine.

The vendor knows their protocol is buggy, because in their PC maintenance software they have arbitrarily chosen to start frame sequence numbering one higher than the escape character so that they can avoid triggering the bug in most cases. It still breaks down when the payload contains that prohibited escape code. Service techs are used to the whole thing randomly requiring retries and constantly joke about how repairing the $vendor's stuff has the best billable hours per work done ratio.


I assume given the rest of the context you were not implementing a FIX parser - but you’d find the same escape code layering violations if you were!




Consider applying for YC's Spring batch! Applications are open till Feb 11.

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

Search: