Let's just say, that I've been bitten more often by missing documentation in large and complex legacy applications rather than outdated one.
If I see a discrepancy between documentation and code, I can always either fix that by updating the documentation or fix the code to follow the documentation. More often, it turns out both are out of sync with business goals and I end up fixing both. In any case, if there is documentation, that does not match code, it raises my flags and I go to the business analyst or architect and figure out the real requirements. If there is no documentation whatsoever, there is no way for me to know what if anything is wrong with the code (besides it being overly complex and unintuitive -- as far as I can tell, the business requirements might be overly complex and unintuitive) Then again -- it is mostly large legacy codebases that have seen hundreds of developers before me that are poorly designed, poorly implemented and almost never commented, that I have had to deal with that make me feel that way, so maybe, if I had any real experience with well designed and well implemented code, I would probably have a different view... 2013/5/2 Fabrizio Giudici <fabrizio.giud...@tidalwave.it> > On Wed, 01 May 2013 10:57:01 +0200, Roland Tepp <luol...@gmail.com> wrote: > > This is so far the best and the most concise comment in favor of code >> comments I've read so far. >> >> Thanks man. >> > > The problem is: redundant comments, in my experience, tends to be always > out of sync with the code after some time. At that point, what's the right > one? The code or comments? :-) If you're testing at a decent level, it's > the code. Thus, what's that redundancy for? > > >> teisipäev, 30. aprill 2013 21:16.39 UTC+3 kirjutas Vince O'Sullivan: >> >>> >>> On Monday, 15 April 2013 07:38:03 UTC+1, brucechapman wrote: >>> >>> If what we write first is "the simplist thing that might work", then >>>> I'd suggest comments should explain code that is not apparently the "the >>>> simplist thing that might work". or "comments should explain why the >>>> simplistic thing that might have worked, didn't" >>>> >>> > > > -- > Fabrizio Giudici - Java Architect @ Tidalwave s.a.s. > "We make Java work. Everywhere." > http://tidalwave.it/fabrizio/**blog <http://tidalwave.it/fabrizio/blog> - > fabrizio.giud...@tidalwave.it > -- Roland -- You received this message because you are subscribed to the Google Groups "Java Posse" group. To unsubscribe from this group and stop receiving emails from it, send an email to javaposse+unsubscr...@googlegroups.com. To post to this group, send email to javaposse@googlegroups.com. Visit this group at http://groups.google.com/group/javaposse?hl=en. For more options, visit https://groups.google.com/groups/opt_out.
