From: James Britt Date: 2005-04-28T09:14:04+09:00 Subject: Re: Comments Are More Important Than Code Dave Fayram wrote: > James Britt wrote: > >>Dave Fayram wrote: >> >>>Your code isn't the place to justify your position >>>post facto. The fact that the code works should be justification >>>enough. :) >> >>Yeah; I've written lots of code that, um worked. It just worked at > > >>the wrong thing. > > > So documentation would solve this problem? I don't think so. Maybe. Certainly, running code is no proof of anything other than that the code runs. Writing out the intent and goal of some class or method before writing the code may help the developer clarify his or her thoughts, such that the code may be more likely to be written correctly. > Unit tests > solve this problem to the extent that any modern solution can. > Documentation is just as likely to lead you astray as help you here. Isn't there the same issue with unit tests? If they aren't testing the right behavior, then they only tell you that have code that passes tests, but not code that does what you intended. In the end, you have to have a clear understanding of what the code should be doing. Comments can help. > > >>I don't see how one goes from writing comments to having a >>documentation-heavy approach. Or how it equates to up-front design. > > > In your next statement you claim you should write the documentation for > a method first, then "convert" it to code. I maintain that this is > "design-up-front". I've had plenty of scenarios where I think I know > exactly what I'm about to code, and then in the process of coding it I > realize that I had it all wrong, overlooked something, etc. Interesting. This sound like, "Just code, don't design at all." If first I write # This should check that a given user name does not exceed # a max length because of reason foo and that convert that to code, have I done "up-front" design? Perhaps. Would creating CRC cards be up-front design? Would that make them bad? > ... > >>But a better approach might be to write the method comment first, > > then > >>convert the comment to code, such that the comment is no longer > > needed. > >> And if you find that you cannot do this, then that may be a code > > smell. > > Maybe it is a smell, but it's the good kind that lets you steer your > code based on what it needs to be, not what you think it ought to be. > See the comment above. I prefer to decide what the code does, not let the code decide for itself. Comments-before-coding are similar to sketching in a drawing on canvas before doing a large painting. No doubt, as a work develops, things will have to change, but that doesn't argue for the elimination of the entire sketch. But perhaps there is case to be made for coding the way Pollock painted. > > I think what you're describing is not only a headache, but inefficient. > If applicable, I'm already writing unit tests. When I'm convinced that > I haven't made a misstep, I'll document it. I'm suggesting that before you write unit tests it may help to have something that explains what you should be testing, and why. > > Documenting untested code (as in, explaining in english an algorithm or > procedure which has yet to be tested, which is a necessity of your > approach as described above) is a waste of time and effort. If you're > wrong, you now have that much more information to change. Same goes for writing unit tests that test the wrong behavior. I see comments as a way of helping ensure the developer is clear on the end goal. > > >>I believe that developers can forget that what seems obvious at the > > time > >>the code is written will often seem cryptic later on, ever to the one > > >>who wrote it. Writing it down forces you to at least make the point >>explicit, and help the coder see if he or she has a clear > > understanding > >>of what code is supposed to do. > > > I believe this is a reaction to poor coding practice, and not a > necessity. I've picked up code that I wrote years ago and managed to > step in with only minor headache. I don't think I'm special, or have > any super-brain-abilities that let me do this. I just happened to work > with someone who made me code with good style and document > appropriately. There was nothing special about it (unless you deem a > college research product being maintainable as special, which it may > be). That's outstanding. Yet I routinely come across code, written by people I have every reason to believe are bright and capable, that is terse, hard to follow, and hard to use. Perhaps those with exemplary coding practices can just code directly, but others may benefit from certain practices. > > Oh, and we had a readme explaining what the code did at a higher level > (*cough*techmemos*cough*). Does that doc lie? Was it written to define the intent of the program prior to coding, or written to explain whatever the code ended up doing after development? > > >>I find the a best way to know if I understand something is to try to >>write about it. It forces me think in a certain way that talking or >>coding does not. > > > Funny, I find the best way to understand it is to *do* it and *test* it > and *try* it. Then, if it seems right and holds water, I keep it. If > not, then I made a mistake and obviously I need to recode it. Again, to go round and round, if you do not already understand something then it may be hard to know when you have it right, even when producing code that happens to run. Being able to do something is not an assurance of understanding what one is doing. ... > > > It's a logically untenable to say what I'm about to say, but I'm going > to say it. If you're still having lots of fits and false starts in > Rails, it is probably because you're not past that awkward first step. That's too funny. Blame the user. This is the sort of thing that makes Rails-rooters so endearing. Um, no false starts. Just getting the feeling that Rails is a DSL that is far more complex that the underlying language, at times making things harder than easier. > > But that aside, are you claiming that Rails needs more documentation? Yes. Or better organization, or pruning. James