4 ms·
I think the best solution is having a few tactical comments. Imo the best setup for a project is: 1. Some high-level documentation explaining how the key syst
by skohan 4y ago
I think the best solution is having a few tactical comments. Imo the best setup for a project is:
1. Some high-level documentation explaining how the key systems work and interact conceptually, to give context.
2. Comments for anything non-standard (i.e. we're using some weird encoding here instead of JSON because of XYZ reason)
3. Comments for the tricky extra complicated bits
For everything else, well-written code following standard conventions and good naming practices is enough.
Also choose a statically typed language, so that your function signatures will give you a useful contract to work with, and it will mostly be pretty easy to trace the intent of your code.
- chriswarbo 4y ago> Also choose a statically typed language, so that your function signatures will give you a useful contract to work with, and it will mostly be pretty easy to trace the intent of your code. Furthering this, avoid: - "Stringly typed programming": where everything has a static type, but they're all `String` (or `Int`, `Float`, etc. instead of something with domain meaning). This gives very little information to the reader, and makes it easy to mix-up values. - "Boolean blindness": where we query a bunch of booleans to determine what data we can extract, e.g. Result::hasUserId : Boolean Whether this result contains a UserId Result::getUserId : UserId Returns a UserID if hasUserId; otherwise error log("Request came from " + myResult.hasUserId? myResult.getUserId : "anonymous guest") Compare this to e.g. Result::getUserId : Option[UserId] log("Request came from " + myResult.getUserId.orElse("anonymous guest"))
- LorenPechtel 4y agoThis. I regard comments as something a bit negative. You use them if you have to but you see if you can write the code so you don't need them. If it's internal to my code I can almost always get rid of the comment, I end up with most of my comments referring to external matters.