Peter Kovac wrote:Hi Guys,
I hope you can answer some of my questions/rants about self-documenting code:
Peter Kovac wrote:Names: names should describe the function but sometimes I feel it's overrated for example:
MergeListsFromResponseInputIfNeccessaryConditionsAreMet - especially if it's used in a call chain:
collectInputDataFromResponeThrowingExceptionIfNeeded (MergeListsFromResponseInputIfNeccessaryConditionsAreMet(.....))
Peter Kovac wrote:
Comments: yes, comments should be informative and terse but banning them is dubious. Why do I have to look through and understand 5 classes instead of reading 3 lines of comment? Besides a good IDE can show you the method comment while coding. Again I'm just saying the comments are not evil if used judiciously. Of course, if somebody modifies code they should modify comments as well - for 3-5 lines this shouldn't be a problem.
Peter Kovac wrote:
Small (3-5 lines) methods: method should be concise, but I don't know which is better:
- create a new method for every 3-5 lines OR
- using comments for code-blocks (for the same 3-5 lines) - still small methods (max. 20-25 lines)?
Peter Kovac wrote:
Creating a new method gives a higher overview when reading the code but
- sometimes it requires a lot of member variables just to store object state
- some code checkers report them as issues.
- some authors says that they're code smell.
Peter Kovac wrote:
Code is the documentation: my (somewhat limited) experience is that in some companies "agile" means no documentation "because there's the code", but If I have to make some changes into an unknown code base I think it's better to read some doc rather than to understand all the codes. Besides I don't really know how design decisions can be reflected in code, at all.
Peter Kovac wrote:
Am I too old schooled? What's your opinion and experience on self-documenting code?
Sorry if this is obvious, but I really want to hear your opinions.
Junilu Lacar wrote:
Your examples take the concept too far. They almost seem spiteful, like something my teenager would do when I tell him he's not paying attention--his response is to pay too much attention. The goal is to reveal the intent, to give the gist of what's being done at that point in the code, at the appropriate level of abstraction. It shouldn't give all the gory details.
Junilu Lacar wrote:
Maybe you just haven't seen the "rules" applied judiciously and effectively.
Junilu Lacar wrote:
The question now is: Are you up to the challenge?
Peter Kovac wrote:Unfortunately the codebase I'm working with uses those long names that's why I might be a little furious..
Peter Kovac wrote:
Yes that might be the case... but sometimes I feel that If a company uses agile it means forget everything that worked before...
Peter Kovac wrote:Do you know any real project that uses self-commenting code effectively?
Peter Kovac wrote:
On the intent-side.. What do you think using asserts for clarifying the goal e.g:
Junilu Lacar wrote:
Peter Kovac wrote:
On the intent-side.. What do you think using asserts for clarifying the goal e.g:
....
Interesting question; .....
Matthew Brown wrote:How about this?
Junilu Lacar wrote:
That "Do one thing and do it well" thing, there will be those who argue that there are some methods where it is impossible to make it do just one thing. For example, what about the dispatch method in a controller class? These methods are delegating to other classes, gathering results, making decisions about the flow of execution, etc. What do you do with these methods?
I have my ideas on how to effectively answer that but I'm curious to see what others might have to say.
Junilu Lacar wrote:That "Do one thing and do it well" thing, there will be those who argue that there are some methods where it is impossible to make it do just one thing. For example, what about the dispatch method in a controller class? These methods are delegating to other classes, gathering results, making decisions about the flow of execution, etc. What do you do with these methods?
Books: Pragmatic Unit Testing in Java, Agile Java, Modern C++ Programming with TDD, Essential Java Style, Agile in a Flash. Contributor, Clean Code.