4 ms·
My personal method is, every line of code that I write, I write for someone else. If it's internal, it's always for another developer (who may not exist) and, f
by nomel 9y ago
My personal method is, every line of code that I write, I write for someone else. If it's internal, it's always for another developer (who may not exist) and, for the upper layers, a user (of the function/API/library) that may peek behind the scenes trying to debug some problem.
If it's anything facing the "user", it's entirely written for that user, and I know they're not very good at reading or writing software.
Thinking about the developer helps prevent me from being lost in complexity, abstraction, or the general specific of the problem. Thinking of the user keeps the game in sight.
In all cases, I've had very "clever" solutions that are fun and challenging, that I completely scrap for something the other developer, and myself, can understand in 3 months.
- gregmac 9y ago> for another developer (who may not exist) You, 6 months from now (or whenever you stop touching this code base), are effectively "another developer". New developers don't seem to really grasp this until the first time they have to maintain their own old code. I don't think it really hits home until the first time you experience: "What is this? Who wrote this garbage??" runs git blame "..oh, crap."
- milkytron 9y agoThis is why I usually throw in comments with myself as the recipient for understanding where complexity exists. I've heard people debate over whether comments should be in well written code, including some that argued comments should never be used at all. Party A: Code should be easily understandable so that comments aren't necessary. Party B: Comments should exist where complexity exists to save a developer's time when determining what is and is not important to them. Sometimes though, you just can't avoid it. The few times I had to write PERL are prime examples.
- humanrebar 9y agoGenerally the best comments are to describe "why" (sometimes "how") more than "what". Of course, good writers know their audience. If that code is somehow strange in its organizational context, a few "what" comments and links to references, documentation, and/or tutorials can be great.
- gregmac 9y agoObviously 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.
- lmm 9y agoIt's analogous to a translation note: any time you need to add a comment is a time where you've failed as a programmer. Sometimes it's necessary, but it should be a last resort. I can well believe that writing Perl would require comments, but to my mind that's a case of "don't do that then".
- Latty 9y agoThis is very much my style. I've found that my approach almost always boils down to "how can I make this obvious". This doesn't mean you can't have complexity, but it should be obvious how to use something, and hard (ideally impossible) to use wrong. A great many projects fail this, or make assumptions about what obvious is. A bit of a digression, but I have found that while I have started shifting towards more strictly typed tooling to facilitate this (the typing can often act as a guide which is easier to understand than prose due to consistency), the projects that tend to do this best are ones in the loosely typed languages. My assumption is that in a language like Python, people are forced to think about what is obvious more because it's so much easier for users to do the wrong thing. As where when you have (for example) a Java system, people just assume that because the types are there, it's self-explanatory.
- wolfgke 9y ago> My personal method is, every line of code that I write, I write for someone else. If it's internal, it's always for another developer (who may not exist) and, for the upper layers, a user (of the function/API/library) that may peek behind the scenes trying to debug some problem. > If it's anything facing the "user", it's entirely written for that user, and I know they're not very good at reading or writing software. In my opinion a very reliable way to get a deep hate on the respective person.