Re:Ruby Patterns from GitHub's Codebase
by whatthefunk on Wednesday February 29, 2012 @10:23PM
(#3650779)
Regarding the part where you say "document everything". I'm assuming you come from a mid-sized company standpoint where there is more than 1 person working on the app. I might be wrong but I think documenting everything from the start is counterproductive.
[ Parent
| on HN ]
Curious as to why you think documenting everything from the start is counterproductive. Are you opposed to documenting everything or documenting from the start, and why?
I mean, I hate writing documentation, but as someone who has had to come back to code I've written months prior (and I was the only one to work on the project), let alone code someone else wrote, I'm incredibly grateful when I look at old code that's actually documented. Plus I feel that writing a couple lines of documentation helps me figure out exactly what I want the code to do.
Re:Ruby Patterns from GitHub's Codebase
by whatthefunk on Thursday March 01, 2012 @04:30PM
(#3654144)
True. I have been in that situation too. Although I also have some cases wherein I thought prototyping something up to a point to prove it's worth is not subject to "document everything." I guess my question now is, is it better to do it from the very beginning knowing this fact?
Since I think accurate, up-to-date documentation is as important as existent documentation, I'm inclined to believe that documenting everything doesn't have to be started at the beginning, but I know the longer I put it off, the less likely I am to actually write it. I've been trying to document my code as soon as I have a good idea of how the function, method, etc. is going to work, which sometimes is before I write any code, sometimes after I'm finished, but usually as I'm writing it.
Re:Ruby Patterns from GitHub's Codebase
by technoweenie on Wednesday February 29, 2012 @11:32PM
(#3650921)
GitHub IS a mid-sized company with more than 1 person working on the app.
If all goes well, you'll be a mid-sized company at some point. I say that from painful experience - we're about to hire our second developer at work, and I'm not looking forward to the time it's going to take to document all those little edge cases that I know about, but they won't.
It really depends on what your end goal is. Building a quick prototype doesn't need documentation, but building a long-lasting app that's maintainable and scales well with a growing dev team, documentation is extremely important.