3 ms·
Obviously the worst comments are utterly obvious: // Get the users name name = get name(); There are lots of cases where inline comments are very usef
by gregmac 9y ago
Obviously the worst comments are utterly obvious:
// Get the users name
name = get name();
There are lots of cases where inline comments are very useful though.
As an example, most of my team isn't strong on regular expressions, so when I use one, I'll usually put a comment explaining what it does in slightly more detail than I normally might (to the point it would be a bit too rudimentary to anyone well versed in regex).
I've also been writing lots of automation scripts for stuff running at AWS lately, which often involves using strange AWS CLI filter syntax, jq expressions (for JSON parsing) and some other random utilities like sed, cut, sort, etc. Even for myself, I put fairly detailed comments, but I don't use those on a regular basis and usage isn't always obvious anyway.
- flukus 9y agoRegular expressions are the perfect use case for unit tests, they are simple input/output pure functions. Not only do you ensure that they work, you provide several examples to future devs of what should and should not be considered a match. On the automation scripts I really need to take a leaf out of your book though, I'm awfully undisciplined at commenting them and it always comes back to bite me.
- gregmac 9y ago100% agree on unit testing regex, but spending a minute to type a detailed comment that saves sometime the extra time of navigating to and reading several unit test cases is worth it. If someone is modifying the regex the tests are essential, but for someone just reading the code why not save them the time?
- daemin 9y agoActually I would consider that a decent comment, since get_name() doesn't actually say what name it is getting. It could have been some other name in the system. This would depend on the context and the surrounding code though.