Skip to main content
Software Engineering

You are not logged in. Your edit will be placed in a queue until it is peer reviewed.

We welcome edits that make the post easier to understand and more valuable for readers. Because community members review edits, please try to make the post substantially better than how you found it, for example, by fixing grammar or adding additional resources and hyperlinks.

Required fields*

10
  • 34
    "Code Paragraphs" should be extracted into their own methods, and given descriptive names. Commented Aug 4, 2011 at 18:21
  • 10
    +10 for this. Selective comments are very helpful. Yes, code can be 'self documenting,' but by adding one line you can understand a whole block of code at a glance, instead of working through each line to figure out everything that it does. Commented Aug 4, 2011 at 18:30
  • 9
    @Adam Jaskiewicz so when you call all of those functions one after another in the function they were removed from, you end up with obfuscated confusion. Should I have to examine all of the c standard library functions to have a broad overview of a program someone else wrote? Commented Aug 4, 2011 at 19:55
  • 7
    @Adam Doing so would needlesly complicate code. I split up methods based on major function, not microtask. If you follow that rule then most projects will have 4-5x as many methods as nessesary. Commented Aug 8, 2011 at 5:29
  • 5
    I don't understand why "dump found entries into a csv file for excel" isn't a method name. A 6 line method dumpToCsv(output); is easily understandable in the scope of the calling method, the scope of the method and doesn't require comments that can rot. Commented Nov 2, 2012 at 13:29