13 ms·
The Code Documentation Fallacy
- dexen 13y ago...and for those who like concise quotes: `If the code and the comments disagree, then both are probably wrong.' -- Norm Schryer `Don't get suckered in by the comments -- they can be terribly misleading. Debug only code.' -- Dave Storer
- userulluipeste 13y agoTL;DR: The people may be stupid, or may do a messy work, therefore it must be the methods they use or the requirements that are faulty in the first place.
- ZoFreX 13y agoBetter TL;DR: Would you rather have 10% of functions commented or 90%? Author argues that 10% is better, if all functions are documented then documentation is obvious, noise, and often wrong. Document the non-obvious cases.
- userulluipeste 13y agoWould you rather go to one extreme or to the other one? Please downvote me again.
- thejteam 13y agoMy problem with code documentation is that documentation is done at the function or class level. When I'm looking at new code I would prefer a "concept of operations" describing how the whole thing works together rather than piecemeal function documentation. This is especially important with open source code. I'm not going to donate my time to working with an existing codebase if it is going to take hours to figure out how it all pieces together. Examples are fine but what I really need to know is the why. At least when I put up with this at work I'm getting paid by the hour.
- ZoFreX 13y ago+1 to this, whether I'm making a quick fix or intend to do some significant work, if I'm diving into an unfamiliar project I am always overjoyed if I find 'concepts and metaphors' documentation.
- jostylr 13y agoThe old classic literate programming paradigm helps with this. It allows one to write documentation that gives you an overview, provides you with whatever ordering and connections you feel appropriate and, with my implementation of it, even takes care of most of the tool chain. https://npmjs.org/package/literate-programming https://npmjs.org/package/literate-programming
- andyzweb 13y agothis brings a smile to Knuth's face
- abritishguy 13y agoThe documentation for Flask does this and it is really good.
- RivieraKid 13y agoI opened the comments with an intention to write basically the same thing. Higher level documentation - classes, packages, groups of packages - makes the project much more approachable. It answers the question "Here's a 3 levels deep hierarchy - where do I start, how are the pieces connected to each other?" Documenting classes is fairly common, but only the public API. I'm not only interested in how to use the class, but also how does it work internally, what is the inner architecture.
- arbutus 13y agoSame. Often I find myself wishing that I could see things as a sequence diagram. I've never worked anywhere where functions were commented with useless English descriptions of the parameters and so on, so I don't really know if this is something that people really do. What I do wish I had was more high-level, visual representations of a system when I'm trying to learn how it functions.
- tjeerdnet 13y agoThis is an ever ongoing discussion between two kinds of programmers (documenting and non-documenting). Just decide for yourself or your team what works best. I myself like to even document other people's code after I see what the method does if the method isn't speaking for itself. If I am developing I want to see in my IDE when adding an existing method, a popup which tells me quickly about what the method does and the arguments it has and what it returns. Instead of (everytime) having to jump to the code to see what it does. Just one simple (real life) example: public String convertText(String text) { return text.toUpperCase(); } This method is already named wrong in my opinion and should be refactored to something like convertTextToUpperCase to understand what it does without having to document. But if your methods get more complex I think a little comment on top of the method describing what's going on really cannot harm. Especially if the code is difficult to read for new people. The point is in the end to keep the documentation in sync with the code and that takes indeed some effort. I myself always make documentation for a method in Java-doc style, so only above the method, if it's more complex than a simple getter/setter-method. I always tend to think in terms of the official Sun Java API-documentation, which I use(d) so often to know how all the classes/methods work, that it might also make my own code more readable/understandable when I or someone else has to work on my code if I have documented it. Inside the method code I try to comment little to not. @snowwolf: I agree, but it's just an example to show that a method name should speak for itself
- lmm 13y ago"Cannot harm" is a fallacy. Every additional comment adds a maintenance burden. Sometimes comments are worth the cost, but they should be a fallback to a fallback - ideally, the code should be self-explanatory. If that's not possible, unit tests should explain the usage and functionality - they're better than comments because the build system enforces that they're updated when the code changes. Only if you can't do that either should you resort to a comment.
- snowwolf 13y agoJust to comment on your example, that method shouldn't exist as it adds no value to the codebase - it is purely redundant code. Especially if you were to rename it to convertTextToUpperCase. The only situation where the method would make sense is if you wanted to be able to change the implementation in the future (TitleCase, LowerCase etc.), in which case a better renaming would be covertTextForDisplayInTitles (i.e. Use the method name to comment why we need to convert the text). That has the added benefit of also telling you what the method does in your IDE just from its signature.
- TheDistantSea 13y agoSo basically the author is making the argument that comment quality is correlated with quantity. As far as I can see, this is backed exclusively with "but the ones that do probably...". Let's just say I 'm not convinced yet.
- lyesit 13y agoI think the argument being made is that comment quality is more important than quantity. The author gave an example where the code with less documentation had more useful descriptions in order to illustrate this point; I don't think he necessarily meant that one caused the other.
- TheDistantSea 13y agoThat's something we can all agree on, but then why bring quantity into the discussion? I prefer lots of useful comments over few useful comments.
- JackFr 13y agoTo paraphrase The Incredibles, if everyone is special, than no one is. If 10% of the functions are commented, I will assume that those 10% are more important or have more error prone or dangerous usages. If every function has a boilerplate comment, I lose that information.
- jfb 13y agoNobody is arguing for boilerplate. The idea that less is more, holding quality equal, is nonsensical. Of course, as documentation isn't free, you can't hold quality equal, so it's immaterial -- nobody is ever going to be presented with that choice in real life.
- Aykroyd 13y agoYou can catch garbage comments in code reviews just as easily as you can catch other forms of programming garbage during review. The fact that someone might make a lot of bad comments is not a good argument against commenting, it's a good argument against bad commenting. I also think that if people are in the habit of having to comment it makes them more likely to document things like expected values of the input, what the return could be expected to be, and if there are any caveats.
- narag 13y agoSo true! This is what happens when comments are produced because some coverage goal. It's sad how comments here are being (on purpose?) misrepresenting the point. Another methodology jihad? Edit: LOL! inmediate downvote. I have my answer now.
- einhverfr 13y agoFirst, I think more documentation always beats less documentation, assuming reasonable quality. What the article is getting at is the idea that documentation for the sake of documentation never results in any quality. When I write a new module for LedgerSMB (I won't vouch for older code either by myself or others) I actually start writing the documentation. The reason here is that the documentation is written primarily to establish the contracts under which the code operates. This includes concept of operation documentation as well. It isn't just aimed at other programmers. It is aimed at documenting the code contracts so that it is clear what are acceptable operations at first. So if there is a fallacy it is not that more code documentation is better (since that is often true, IMO), but rather that telling people to document for the sake of building documentation works.
- jheriko 13y ago"What the article is getting at is the idea that documentation for the sake of documentation never results in any quality." X for its own sake is rarely good.
- mhaymo 13y agoThe less that is described by the signature, the more necessary it is to document a function. In C++/C#/Java, while the parameters and return values are often fairly obvious, exceptions are completely undocumented by the type system (unless you use Java checked exceptions, which you shouldn't), and so should be documented manually (and asserted in unit tests, to ensure the documentation doesn't become incorrect).
- progx 13y ago"As a rough estimate, 95% of functions in any code base should be so simple and specific that their signature is all you need to use them." Welcome to reality! What is simple for one guy is really hard to understand for an another one. What you expect is that every bigger function must be split into dozends of smaller functions, only to have a cleaner parameter part. But this make the code flow unreadable.
- kyberias 13y ago> What you expect is that every bigger function must be split into dozends of smaller functions, only to have a cleaner parameter part. But this make the code flow unreadable. That's exactly what every good, experienced developer tries to do: Splitting complex stuff into more simpler functions that are easier to understand. Obviously the end result is not unreadable, on the contrary!
- mathattack 13y agoThere's a principal/agent problem with documentation too. The writer of it rarely gets the benefit. Many times they will never see or meet anyone who does. But they have a lot of other competing priorities from highly visible requesters. I am interested in examples of companies that get this right.
- redblacktree 13y agoI agree with this assessment. Whenever I have the opportunity to get feedback from someone who has used my documentation, I make every effort to get it, and then update the documentation. It's gratifying to know that someone benefited from it.
- exch 13y agoI think the article hits on the wrong conclusion. Don't write less documentation because you're going to assume it will all suck anyway. Insist on writing better documentation instead. Having said that, I find it helpful to write documentation before writing the actual code. Specifically for more complex code pieces for which the behaviour is not immediately obvious. For me, writing documentation serves as a form of 'rubber duck debugging'[1] before the actual bugs occur. Explicitly writing out the intention of a piece of code in plain English often makes the concept much clearer in my brain and immediately brings out possible problems with my initial design. Problems I can fix before wasting time iterating through code implementations. This is also the reason I very much enjoy writing thorough READMEs for each library I produce. These explain in abstract concepts what the entire library API is intended to accomplish. Additionally, I try to include actual usage examples. As with code-level documentation, this brings up possible problems before they occur. The fact that it makes it clear what the code does, months after I last worked on it, is entirely bonus. [1]: http://en.wikipedia.org/wiki/Rubber_duck_debugging http://en.wikipedia.org/wiki/Rubber_duck_debugging
- NickPollard 13y agoThe best kind of documentation is that which is checked by the compiler and guaranteed to be correct - the code itself. Code that is well written, in good style using sensible variable names, can be as descriptive as good comments. Using a good static type system allows you to encode properties into your code that are guaranteed to be valid. I certainly think some comments have their uses - but these are generally at the level of how systems and modules work, and the concepts used therein, as discussed elsewhere in these comments. I agree with the article that only 5% (or less) of functions need individual comments attached.
- Jtsummers 13y agoThis depends entirely on your language and environment. Working on embedded systems, where memory is at a premium, the way an algorithm or data structure is coded up may be entirely non-intuitive, merely to get under the memory limits or to eke out a bit more performance. Good documentation + good code is far better than just good code.
- Jare 13y agoI personally think that leaving a function-level comment snippet empty is better than either filling it with useless information, or not having it at all. It serves as visual separator, and it's ready for me to fill when I have something to write.
- Zikes 13y agoI don't get it, having a few comments scattered about in the source code is better than having a separate document that fully and succinctly explains the application API? And what's to stop you from putting the comment about race conditions in the Doxygen-style comment?
- brandonbloom 13y agoSingle-to-noise ratio. You can put it in there, but I probably won't read it. I basically assume that all javadoc/doxygen-style summary/@param/@return-style docs are entirely noise. I much prefer the "docstring" style comments, especially though in Clojure, or Python. Examples... Clojure: user=> (doc map) ------------------------- clojure.core/map ([f coll] [f c1 c2] [f c1 c2 c3] [f c1 c2 c3 & colls]) Returns a lazy sequence consisting of the result of applying f to the set of first items of each coll, followed by applying f to the set of second items in each coll, until any one of the colls is exhausted. Any remaining items in other colls are ignored. Function f should accept number-of-colls arguments. Python: Help on built-in function map in module __builtin__: map(...) map(function, sequence[, sequence, ...]) -> list Return a list of the results of applying the function to the items of the argument sequence(s). If more than one sequence is given, the function is called with an argument list consisting of the corresponding item of each sequence, substituting None for missing values when not all sequences have the same length. If the function is None, return a list of the items of the sequence (or a list of tuples if more than one sequence). And on the far other end of the spectrum, here's some C# / MSDN docs: Syntax public static IEnumerable<TResult> Select<TSource, TResult>( this IEnumerable<TSource> source, Func<TSource, TResult> selector ) Type Parameters TSource The type of the elements of source. TResult The type of the value returned by selector. Parameters source Type: System.Collections.Generic.IEnumerable<TSource> A sequence of values to invoke a transform function on. selector Type: System.Func<TSource, TResult> A transform function to apply to each element. Return Value Type: System.Collections.Generic.IEnumerable<TResult> An IEnumerable<T> whose elements are the result of invoking the transform function on each element of source. Usage Note In Visual Basic and C#, you can call this method as an instance method on any object of type IEnumerable<TSource>. When you use instance method syntax to call this method, omit the first parameter. For more information, see Extension Methods (Visual Basic) or Extension Methods (C# Programming Guide). Entertainingly, this is only one of many overloads in the C# version. The Clojure and Python functions are variadic with parallel traversal of collections. Those languages spend their precious docs space covering the corner cases.
- ddebernardy 13y agoOP is a bit extreme in his conclusions, but not entirely incorrect either. Insofar as I've experienced, there's a mostly finite amount of goodwill that will go into commenting. Extra comments once that limit is reached tend to be sloppy or useless. Essentially the same for unit tests.
- oaktowner 13y agoOne thing to bear in mind is that documentation serves two different audiences. One audience is the people who will use your code. For them, every external method should be properly documented (sure, use a tool for this). And make sure it's good enough that (barring debugging situations, because you wrote perfect code) your "users" never have to look inside your code. (If I think about this in C++, I think you should be able to look at a properly commented header and never read the code) And then there's the poor slob who's going to come in and debug/fix your code some day. He may not need to have every method doc'd but he damn sure needs to know what's tricky, what's interesting, where the gotchas are, etc.
- informatimago 13y agoOk, the problem is not the documentation. It's the specifications. This problem is exacerbed by management methods such as Agile/Scrum, where no specification document is built from the collection of task descriptions stored in Jira (and IF you are luck to have anything significant in the task descriptions, more often, from what I've observed, it's hand waving and shin pointing than anything precise written down). And even if some specification document is written, it still remains the problem because when going thru all the phases of analysis design coding and debugging (whatever the period of the cycle you use), it is not updated! Now we should probably distinguish API elements from internal implementation stuff (but the blog article mentions APIs). When documenting internal stuff, unless you've developped internal APIs (which you should do!), the documentation can indeed be descriptive, to help maintainers orient themselves and avoid pitfals. When documenting API, what you need mainly, is the specifications of the API. This will be the "contract" with the client code, and if there's a discrepancy between the API specification and the implementation, then it means there's a bug (somewhere, of course one could decide that the specifications where wrong, and need to update the specifications instead of the code). Most often it will be a bug in the code. But the point is that either you have tools to track the specifications elements down to the line of code, so that when you create or modify a line of code, you have easy access to the specifications, or you put the specification in the docstrings (documentation comments) in the code, to get the same easy access. And note that this is a read/write access: specifications may need to be updated when the code is maintained. So I would agree, write less documentation, write more specifications. Close to the code.
- redblacktree 13y agoI tried a google search for "shin pointing" and only got pictures of people doing literally this. I got it from context, obviously, but can you explain this turn of phrase to satisfy my curiosity?
- informatimago 13y agoi meant it quite literally. You know, in real life meetings, with body language, odors, hand waving and all that non verbal communication. If everybody knows what we're taliking about, then what's the point of writing it down? Yeah, right. Come back six month later and with half the team turned over, and see how useful thos old Jira tasks with no writte specifications will be useful...
- jheriko 13y agoi think this is still a half way house. code is documentation. bad source code is hard to read, or in practical terms - slow to read. good source code has minimal comments and documentation. writing documentation before you actually need it is often a waste of time as well. at this point surely you have a design to follow, or something other than a brainless application of 'documentation' to store that valuable information into? as many commenters already point out what you almost always want is very high level documentation, and I think this should be present as a design (assuming you have one), if you don't have one then you need a wiki or something. Something that doesn't pollute your code with garbage...
- acjohnson55 13y agoI've done plenty of dynamic language work where some documentation would go a long way. In Javascript, every library function should explain what all optional (i.e. undeclared or reinterpreted) parameters do, what gets returned, and likewise for all callbacks, plus `this` points to. It's very stylish for some insane reason not to do this, and it drives me insane.
- mercurial 13y agoDon't get me started on Javascript. It's a problem with dynamic languages in general - the signature does not document what interface the parameters should implement (eg, a parameter 'file' may be a file path or a file handle, but you'll only know that by looking at the implementation), but it's particularly egregious when nothing tells you at first glance which parameters are optional. I've now started to document public functions. As my classes usually have few public functions, but many private ones, the code to comment ratio remains acceptable, though maintaining the documentation remains a challenge.
- bookface 13y agoAgreed completely about how awful dynamic languages can be in this respect. I've found what helps a lot is consistent naming of parameters. For example, numberOfWidgets (an integer) versus widgets (a collection) or file (a file handle) versus path (a string).
- mercurial 13y agoSure, consistent naming helps a lot (though I'm partial to short-yet-readable alternative like widgetCounts). Sadly, sometimes ambiguity is unavoidable. And other times, you're just dealing with bad code. But consistent naming does not help with the "optionality" of parameters.
- acjohnson55 13y agoIn that sense, dynamic languages often have a jump on their functional counterparts. Relying on the type annotations for all documentation is probably the other side of the coin. I understand that generic combinators sometimes need sufficiently general argument names, but even then, there's often some semantic meaning that can be attached with a self-documenting variable name. Enough with the 1- and 2-letter variable names!
- jarrett 13y agoMy rules for good docs: 1. Begin with a usage synopsis in the form of sample code. It should hit the most important functions and show how they fit together. E.g. for a drawing library, show how to instantiate an image, draw a circle with arbitrary fill and stroke colors, and write the image to disk. 2. For each function or method, open your comment with a straightforward description of what the function does, even if it's absolutely, undeniably obvious. If you're writing an math library, you should even say what the sqrt function does. It doesn't hurt, it costs you very little effort, and you might help someone who's just beginning to learn about the problem domain. 3. For each parameter, document its possible types if your language doesn't encode that information in the function signature. Even if you're using something like Haskell where it does, you might need to comment on the type. E.g. if sin takes a float, say whether it's in degrees or radians. 4. Provide sample code for functions that have to be used in tricky ways. E.g. if the function requires special setup or context.
- samatman 13y agoIn many languages, the 90% comments from this article are "doc strings", while the 10% comments are actually comments. They have different uses, and should be treated accordingly. I also don't understand the fear that doc strings will go out of date. At least with dynamic languages that's part of the point: if the doc string is wrong, then either the contract has changed and not been updated or the code is fulfilling the wrong contract. Both are useful things to know. More often, the doc string is correct, and serves both as a guide to the code "here is what you are about to read" and as a quick summary. if you're trying to decide, say, between iterate-dirs and walk-dirs, that summary is perfect, while reading the code would be an annoying digression.
- azov 13y ago> When some coder changes the function, it is very easy to forget to update the comments It isn't. All public APIs should have documentation, even if you believe it's obvious what they do. This documentation never goes out of date because once you release your API it tells you what you cannot change. If you changed the code so that your documentation is now wrong - this code change is a bug and you should fix it. Because there's other code in the wild that relies on the behavior that you promised. Of course in practice you do have to change that behavior every once in a while. But this should be a big deal (that usually includes bumping up version numbers, mentioning it in release notes, etc). If you're changing it so often that updating the damn comment is an issue you either document implementation details that don't belong in API documentation or your API is unstable crap and nobody should be using it. PS. Complaining that API documentation gets out of sync with the code is like complaining that unit tests break when you change the code. Duh - that's what they are there for!
- j_baker 13y agoYou can change an API without removing functionality. Sometimes you want to add functionality. Or sometimes the context around the API changes. Like for example, a python API might not function the same in Python 2.5, Python 2.7, and Python 3. All I know is, I help maintain a very large set of public APIs that my team is very resistant to changing, and yet somehow the docs are still out of date.
- gobengo 13y agoIs that because you're not updating your docs?
- jdmt 13y agoI don't disagree that public APIs should be well documented. However, I believe it's very easy to forget to update the comments. Especially in scripting languages without type safety. There is little to remind the programmer that arguments were added, types were changed, argument order was modified, behavior was changed, return value was changed, locking behavior was changed, memory allocations were changed, etc. Obviously unit tests should help catch many of these changes. However, it's still up to the coder to remember to change the comments. When you're behind on a deadline or you're juggling 50 different API changes because you're still alpha I'd say it's pretty easy to forget to update a comment. See http://api.jquery.com/jQuery.ajax/ http://api.jquery.com/jQuery.ajax/ if you want an example of on API that could easily have a few typos in it. Who is checking to make sure it's 100% in sync with the code 100% of the time? Not trying to say this example has bugs in the docs but there's a LOT of behavior described that could be out of date.
- pasbesoin 13y agoAt its best, documentation (or a subset thereof) can and does serve as a cross-reference -- like a cross-reference in an important calculation. If the two results don't correspond, you know you have a problem. (Even if you have to explore both paths to learn what the problem really is and where it lies.) Something to consider, the next time you find yourself inclined to complain about documentation. Is it the documentation, or the fact that it's not useful documentation?
- thomasmeeks 13y agoDocumentation does not exist for your own benefit. It exists to help other people on the team, or the programmer that inherits your code, quickly understand your code. The key word here is quickly. Yes, a programmer can trace code & figure it out. On a large chunk of code, however, that is exceedingly inefficient. Whether or not documentation is obvious to the person that wrote it is a very poor test for the documentation's utility. I used to hold a similar opinion -- "Document the non-obvious". The problem is that in a project of sufficient size, almost everything can slide towards non-obvious. Is price the base price, or unit price * quantity? Is the method name cancel_subscription_and_notify_customer really effective? Of course, I could use cancel_subscription, but then I'm not telling programmers about the email that goes out, or cancel_subscription_and_notify, but who am I notifying? The marketing department? Generally I find really descriptive method names to get unwieldy very fast. Further, if you say document the non-obvious, the tendency is towards zero documentation. The value statement depends on how fast your team grows or changes, and the expected lifetime of the project. If you are working on a project alone, and that will never change (e.g. it isn't something a business relies on), then you probably do not need documentation. This is also true if you are bringing on a dev a year, and the team size will always remain relatively small. Similarly, if the project is relatively short-lived (like a game), then dropping documentation could be a good idea. Maybe, I'd at least concede there are merits to doing so. Documentation isn't free, of course. On the other hand, if you are working at a company that's trying to rapidly grow, needs to bring on devs quickly, or has developers moving from one project to another frequently, then I'd say documentation is very important. You are going to save your team a huge amount of time by taking a little time upfront to explain what you are doing, why, and the consequences of each method. Even simple methods deserve documentation for consistency sake. If your documentation rots, then you handle it the same way as test rot. Make sure the team knows that docs are necessary, they need to spend the time on it, and if that means more time for features, so be it. I can say from experience that writing documentation after the fact is pretty gnarly.
- paulgrayson 13y agoThe "turing test" of comments.... If I can distinguish whether the comment was written by a human or generated by some auto-documenting software then the comment may be useful; if I cannot tell whether it was written by a human or auto-generated then it is useless.
- tsiki 13y agoProbably all of us agree that being forced to comment everything will lead to some bad/useless comments. But the examples you showed were simply bad comments. Just because there are bad coders out there who don't care about the quality of their comments for whatever reason, isn't a reason to avoid comments. I'd treat anyone who wrote that first sample comment in a similar way I'd treat a programmer who writes unreadable code; that is, probably take the time to teach them some good commenting practices. Many of the reasons that speak against commenting apply to good variable names, too. Maybe someone will come later and change the way the variable is used but won't change the name. It doesn't mean we should avoid descriptive variable names, though. Also, with comments, as with any form of communication, the audience is the key. Let's say I'm a senior programmer somewhere and I'm writing comments. Often the train of thought seems to be "well, using this variable name/adding this comment clears it up for me". But that's usually not nearly enough for junior coders who are new to the codebase, and who are often the target audience. They'll probably still go "wtf" after reading a comment aimed at a senior programmer with an understanding of the codebase and a programming experience to match. In addition, the obvious point to make is also that code is good at answering how, not why. This is a bit of a pet peeve of mine, I guess since I've met relatively many coders who claim that good code should comment itself and ditched commenting altogether. Their code has usually ranged from above average to downright awful, and has, on average, been rather unreadable.
- efnx 13y agoI think the effectiveness of guessing what the function does by its parameters' types and its return type depends on whether or not the function performs side effects. That said, if it doesn't, or can't (even better), then the name and types should be documentation enough.
- mixologic 13y agoI'm surprised nobody has mentioned Master Foo and the Programming Prodigy. http://catb.org/esr/writings/unix-koans/prodigy.html http://catb.org/esr/writings/unix-koans/prodigy.html
- djyaz1200 13y agoSaw a group pitch a product that was like RapGenius for code documentation, don't think it went anywhere? Both writers and users could add their commentary in a layer that was separate from code, seemed like a clever way to address documentation?
- deleted 13y ago[deleted]
- dancecodes 13y agoMy emacs+doxymacs doing it semi-automatic - I dont know how, but hope these tags @param will show flyhelp at mouse pointer when moving over params. Eclipse doing that but not emacs currently. Its all that I need. Often forgot parameters description and orders. But agree often documentation older than code. Its very fast older and add many noise.
- adamconroy 13y agoI personally favour only commenting on the unusual. I also think that if you are doing TDD then the tests should do a good job of documenting the code. I can't count the number of times someone has asked me to explain some code I have written where my first response is "okay, let's look at the tests". All that being said, it really depends on the scenario. My second last project was a shrink wrap product development that ran a million dollar plus accompanying piece of hardware. This project quite rightly required us to write thorough and consistent comments and docs. Expensive product, complex code, high risk = thorough docs. I am currently working for a small rapidly growing and changing business, where the software is mostly internal. Low risk, quick development required, constant change, low complexity = waste of time and money creating and maintaining good docs
- NAFV_P 13y agoAs an amateur coder I started commenting in my code only recently. There are two main reasons for this, to enable others to read my code more easily, and secondly to enable myself to read my code more easily. printf("If you use C macros"); int _i=1729; while(_i--) printf(" that are defined in terms of other C macros"); printf(", you will be in a world of hurt " "unless you have good documentation written by a human.\n");
- restlessdesign 13y agoHere is a box. You can choose to have it filled 90% of the way or 10% of the way. Most would choose 90%, right? But guess what— THE BOX IS FILLED WITH BEES!
- dllthomas 13y agoIf I'm a beekeeper, that might be what I want...
- digitalmaster 13y agoPersonally, I would rather a useless comment (which I will ignore if the endpoint signature is self explanatory) than no comment at all.