7 ms·
I practice something I could only describe as “comment-driven development”. Whenever I need to implement something non-trivial, something that might have subtle
by branko_d 4y ago
I practice something I could only describe as “comment-driven development”. Whenever I need to implement something non-trivial, something that might have subtle edge cases or has to be done in a certain way because of the external dependencies, I first write the comment before writing the code. I might iterate on the comment, not unlike one might iterate on a design document, and basically use it as a mental tool to fully understand the details of what needs to be done. After I do that, I use the comment to remind me about all these details as I go through the implementation.
All this is doubly important when designing an API, where the comment (also) serves as the externally visible documentation for that API. It helps me put myself into the shoes of the caller reading that documentation without knowing the implementation details, which I believe helps me design a better API.
I hear that “comments go out of date” a lot, but in my case, if a comment doesn’t match the code, it’s usually the code that needs fixing.
- dotancohen 4y agoI do the same thing. I then replace the comment with a method name that describes exactly what the comment described, e.g. _getLowestFooIdFromBarCollection(). I then implement the code inside this private method.
- rlayton2 4y agoSimilar to my strategy. Write the code as if I had all these magic functions that did steps: def write_report(): db = connect_to_database() data = get_data(db) summary = summarise_data(data) save_report(summary) After this, do the same for each of these functions.
- adolph 4y agoI do pseudo code sometimes too. I notice that your functions/methods/whatever are verbs that are assigned to nouns. It reminds me of: Verbs in Javaland are responsible for all the work, but as they are held in contempt by all, no Verb is ever permitted to wander about freely. If a Verb is to be seen in public at all, it must be escorted at all times by a Noun. http://steve-yegge.blogspot.com/2006/03/execution-in-kingdom-of-nouns.html http://steve-yegge.blogspot.com/2006/03/execution-in-kingdom...
- andirk 4y agoHere's to looking at you `get` and `set` decorators.
- ParetoOptimal 4y agoTop down design is great. Especially in Haskell where you can stub those functions as undefined and get type checking along the way.
- marcosdumay 4y agoUsually, when I do this, I immediately end up with a comment that doesn't reflect the code, and is cut and moved around so many times that it's not legible anymore. So I try to replace the comment with code, at once or piecewise (on what case, the comment doubles as a TODO list) during the process.
- andirk 4y agoI believe "TODO" comments are valuable and should be left in; it shows the author also understands there's a better way, once it's viable. Most of my professional colleagues do not agree. I swear it's an ego thing.
- radarsat1 4y agoI believe this is due to how IDEs have introduced useful features to elevate things like specific comment structures like TODO into something "official" and recognized and reported on. So things like a quick "let's improve this part later, but this is fine for now" become items that are highlighted as not "DONE" and then are seen as eyesores or unprioritized tickets, which leaves a bad feeling for devs. While I think these features of automatically tracking TODOs can have their uses, like most things if they become metrics they start to lose their value. Sometimes it's better to just have a keyword you can easily grep for when you do find some time, having these results show up as cases against your abilities to finish the work is unhelpful, but that's what the manager and maybe coworkers see, unfortunately.
- marcosdumay 4y agoHum... Your comment reads like "I have this very specific and subjective process that works for me; people that do things differently are too egocentric to notice their incompetence". Your colleagues may react badly to that style. I believe (but I'm not sure) I do get what you re trying to say, but not every TODO reflects some eternal trade-off. Some are for real clear improvements (like the "there isn't any code here" into "the code was written" on my example) whose history won't add any value after they got done.
- mjrpes 4y agoThat sounds a bit like Donald Knuth's method of literate programming: https://en.wikipedia.org/wiki/Literate_programming https://en.wikipedia.org/wiki/Literate_programming "The literate programming paradigm, as conceived by Donald Knuth, represents a move away from writing computer programs in the manner and order imposed by the computer, and instead gives programmers macros to develop programs in the order demanded by the logic and flow of their thoughts.[4] Literate programs are written as an exposition of logic in more natural language in which macros are used to hide abstractions and traditional source code, more like the text of an essay."
- codemonkey-zeta 4y agoI would go so far as to say it is literate programming. People tend to think literate programs require an extensive system to support them, such as org-modes's emacs integration, or weird meta-programming facilities, but the truth is a program written in any language that support comments can be literate programs, so long as the content of the comments dominates and dictates the structure of the code -- which is exactly what GP commenter's method sounds like.
- sicp-enjoyer 4y ago> so long as the content of the comments dominates and dictates the structure of the code The key feature of literate programming is separating the order that code is written in from the order that the compiler requires, not comment to code ratio.
- TheSpiceIsLife 4y agoAs conceived by Donald Knuth. Literate Programming as conceived by codemonkey-zeta is as described above.
- codemonkey-zeta 4y ago> The key feature of literate programming is separating the order that code is written in from the order that the compiler requires But what's the purpose of divorcing code execution order from the machine, and instead tying that to prose? It's simply to facilitate the reader's understanding of the logical structure of the program without the superficial parts. Just because you do discuss those superficial features with the "literate-programming as code comments" paradigm doesn't make the program less literate, it just means the prose has to be less efficient. I do agree it's better to use a system like org-mode for literate programming because it is better to separate the description from its execution, but I'd argue it isn't really the essential element of literate programming.
- dboreham 4y agoI've been doing this for decades. Possibly influenced by beginning my career coding in assembly, os possibly by Knuth.
- ouid 4y agoit is natural that the first language you would choose to write your program in is something that you can natively compile.
- swayvil 4y agoI do the exact same thing. Psuedo code it up and that's my comments basically.
- taneq 4y agoI do this too, and it’s great. I’d much rather rewrite a comment six times and then write a function once than rewrite the function and re-modify all affected code six times. Also, difficulty writing a clear, concise comment is a strong code smell indicating that you don’t sufficiently understand the following block of code. Much better to realise this at the comment stage than at the debugging stage.
- andirk 4y ago> I’d much rather rewrite a comment six times Yes! Rewrite that comment until it's sound! Being able to write in spoken language what the code is doing is so often related to the writer's ability to write that code succinctly.
- tomcam 4y agoVery similar situation here. I have always approached my code, my codes documentation, and the actual user documentation with this attitude: I assume that someone in the future looking at it will be on their first day on the job, and may not be familiar with the context I am so familiar with.
- wruza 4y agoI’m not too lazy for comments, but I hate it when the flow of explanation/logic gets piled up with details, all in the same visual style. A source becomes a lenghty book with randomly discussed topics mixed with code. Instead of comments I’d like to emphasize some parts and write irrelevant details and technicalities in a smaller font with a lower contrast. And/or collapse parts of it, but with manual collapse statements, not whereever program syntax allows (I find this completely useless). Also abbreviate expressions into comments that by default replace them completely. E.g. <cycle through params and start a service for each one> … <set up an ocr subprocess and handle errors> … if (<is a numeric string>) { <trim whitespace> <extract integer part> <send it to /path/to/route> } expands into a corresponding full-page code and more details when you click on these parts. Can’t simulate fonts and colors on HN, sorry. This isn’t exactly literate programming, but more like a programming markdown. I wish it was every language’s way to go. I know you can simulate that with functions and IDE, but having a continuous context has its own benefits (you don’t have to pass it around, which is tedious and again technical), and also naming things properly and in a unique non-polluting way is hard.
- aliqot 4y agoI ran into this issue and have settled on very descriptive naming for variables, functions, classes, objects, what have you. I still comment a lot, but it's things you might not infer from the naming conventions. Even when I don't think anybody will ever see the code I do it this way because when I open it up a year later to expand, between the git logs and my comments I'm ready to rock right away.
- ParetoOptimal 4y ago> I ran into this issue and have settled on very descriptive naming for variables, functions, classes, objects, what have you. readingCode likeThisKind reallySeemsTo absolutelyDdosMyBrain especiallyAsTheNamesGetLonger.
- andirk 4y agoThere are TwoHardThings. I'll take longer descriptive names any day. There is a discussion whether the prefix of words like "get" (i.e. `getName()`) is necessary. Please keep as rare as possible the describing of the _type_ of object, like `MyDataDTO`, `ListOfPeopleArray`, `ApiRequestObject`.
- osigurdson 4y ago>> it’s usually the code that needs fixing On larger teams the likelihood than comments get out of date is probably higher - particularly if the original comment was very long and detailed and the original author has moved on.
- AlotOfReading 4y agoThe number of times I've seen obscure code that would have been elucidated by a good comment is vastly higher than the number of times I've seen outdated comments. Funnily enough, most of the outdated comments I can remember were dead docs links despite that being a very common 'solution' to the problem of outdated comments.
- osigurdson 4y agoMy experience is the opposite for the most part.
- AlotOfReading 4y agoWe might read different kinds of code, perhaps? I do lots of systems work where obscure hacks to work around toolchain and hardware issues are common.
- foomatic 4y agoSounds like software design process done poorly
- rideontime 4y agoCan you elaborate on that?
- foomatic 4y agoCode comments are implicitly associated with code that already exists. Sounds like your making a presumption about what code exists and potential missing the forest for the trees.
- andirk 4y agoComments on non-trivial code is invaluable. I do it constantly and appreciate traversing previously made comments, especially when beyond short-term memory. Regexes, multi-conditionals, all those weird edge cases. How does any of that go "out of date"? As time progresses, comments become _more_ valuable, not less. What is the use case where comments are bothersome or out of date?
- VBprogrammer 4y agoComments about what something is doing are both the least useful and most likely to go out of date. Comments about why something is happening are in my experience much more useful. An example: # Using an if / elif rather than a select here Rather than: # Use a large if / elif statement here due to a regression in TCL 8.4 which made select statements significantly slower. See GitHub.com/tcl-bugs.
- dceddia 4y agoFor figuring out how to build complex systems I’ve started doing something like this too, but in prose form, in a separate document, purely as a form of thinking through how the pieces will all fit together. Most recently, it was for building a multitrack video player, and working out how to organize the various parts (decoders, mixer, compositor, player, handling seeking, etc etc). I drew out a TON of block diagrams while constantly feeling like they were missing the how and the why, and then I sat down and wrote out my thoughts it helped a lot with getting clear on how it would work.
- flatline 4y agoI did this early in my career then stopped when I realized it generally made the code less readable. Generally, not always. Sometimes a comment about what the code does is invaluable if it’s complex, but usually it is redundant with reading the code directly. I feel like coming across code littered with comments about what the next line does reflects someone not cleaning up after themselves, a string of trivial comments would not pass code review on most teams I’ve been part of.
- 314 4y agoThis applies to comments about single statements in the code, unless they have an esoteric side-effect or there is a particular why that needs to be explained. But comments that describe a paragraph/block of code have a separate value. Being able to skim code faster because of a series of well chosen sentences is an aide beyond clear code. As the OP described it is a good way to design before the code is written.
- softfalcon 4y agoI definitely do this as well when I have a complex feature or pattern I need to implement. It’s best to break down the problem into solvable chunks and writing the comments out first helps you break it apart and also make sure you haven’t missed anything. This is the stuff that a software engineering professor will tell you to do, you ignore it for years, and then later on, after you’ve matured, you find yourself picking up again because it’s just one of those incredibly simple and responsible ways to break down complex problems.
- rewgs 4y ago> It helps me put myself into the shoes of the caller reading that documentation without knowing the implementation details. I program the same way and wish more people would consider the audience when writing code.
- raffraffraff 4y agoLike TDD-lite :)
- eloff 4y agoI've also hit on doing this as well. I find it really helps to organize my thoughts, uncover edge cases, etc before I start to write code. Then I might start sketching the implementation with function signatures docs, types, loops and calls, and gradually start filling it in beginning with the parts that are less clear to me.