I was referring to the comment above, the docblock. That's why I said specifically the black box functionality is documented. I'm not here to criticize the Joomla CMS, I was showing you an example where comments have been helpful to me. The comment implies the pre and post conditions of the method, and states the side effects. It also enhances the semantics of the parameters. I'm talking about the signature of the function ( hence the made up term mental encapsulation ), not it's implementation. My point is further demonstrated in that the implementation was overly complex, so the docblock was especially helpful.
Thanks, I'll go read those beginner books right away when I finish the 25 other architecture & design books I'm sitting on.
What is the essence of good software design
Moderator: General Moderators
-
alex.barylski
- DevNet Evangelist
- Posts: 6267
- Joined: Tue Dec 21, 2004 5:00 pm
- Location: Winnipeg
Re: What is the essence of good software design
I see...my bad. My understanding of the conversation pytrin and I were having was that we were focused mostly on inline comments, not docblock. My method of maintaining external API documentation is just as effective as inline so for me it's not relevant, admittedly I didn't even consider that.That's why I said specifically the black box functionality is documented.
It is complex, which demonstrates why the original developers used redundant/misleading comments. If something is complex enough to warrant commenting, then something is clearly wrong and needs to be refactored or further decomposed. That was point.My point is further demonstrated in that the implementation was overly complex, so the docblock was especially helpful.
DocBlock API are more akin to applicaiton documentation than commentation...there is a bit of a difference which explains my confusion when you posted that code. API documentation = YES, implementation commentation = NOT SO MUCH.
Haha...ok then. Just so you know...I had aThanks, I'll go read those beginner books right away when I finish the 25 other architecture & design books I'm sitting on.
Just out of curiosity, what books are you reading?
I have:
1. Head First Design Patterns
2. Microsoft Press Software Requirements Patterns
3. Code Craft
All three are available for trade if you have anything you've finished and wish to get rid of in exchange for a trade? If fact I have a few books I'd like to trade in for something else...mostly C/C++ particularly for Windows, if your interested?
I wouldn't mind getting CodeComplete 2 or a book strictly on refactoring.
Re: What is the essence of good software design
I'd be willing to trade you some books, not certain ones though.
Here's an excerpt from Martin Fowler's Refactoring:
"refactoring can lead to simpler designs without sacrificing flexibility. this makes the design process easier and less stressful. once you have a broad sense of things that refactor easily, you don't even think of the flexible solutions. you have the confidence to refactor if the time comes. you build the simplest thing that can possibly work. as for the flexible, complex design, most of the time you aren't going to need it."
Some of the books I was referring to,
test driven development by kent beck, the pragmatic programmer, event based programming, analysis patterns, design patterns (GoF), OO methods ( foundation edition and Object-Oriented Methods: Pragmatic Considerations edition ), patterns of enterprise application architecture, refactoring (as was mentioned ), domain driven design,
Object-Oriented Software Construction,
Art of Computer Programming, The, Volumes 1-3,
Pattern-Oriented Software Architecture Volume 1
Object-Oriented Analysis and Design with Applications,
Working Effectively with Legacy Code,
Refactoring to Patterns, implementation patterns, How the Mind Works, The Language Instinct: How the Mind Creates Language, Pragmatic Thinking and Learning: Refactor Your Wetware , Domain-Specific Application Frameworks: Frameworks Experience by Industry, Don't Make Me Think! A Common Sense Approach to Web Usability, Object Solutions: Managing the Object-Oriented Project, Object Oriented Software Engineering: A Use Case Driven Approach , IBM Office Systems: Architectures and Implementations by Martin, Principles of Object-Oriented Analysis and Design, Object Oriented Analysis, Structured Analysis and System Specification, Practical Guide to Structured Systems Design, Designing Object-Oriented Software
maybe not 25 i was just throwing that number out there to show off
i got some more domain specific books though that I didn't list, some of these are still on my wishlist, including a few I didnt mention.. feel free to buy them for me
http://www.amazon.com/gp/registry/wishl ... P7FT2ER523
Here's an excerpt from Martin Fowler's Refactoring:
"refactoring can lead to simpler designs without sacrificing flexibility. this makes the design process easier and less stressful. once you have a broad sense of things that refactor easily, you don't even think of the flexible solutions. you have the confidence to refactor if the time comes. you build the simplest thing that can possibly work. as for the flexible, complex design, most of the time you aren't going to need it."
Some of the books I was referring to,
test driven development by kent beck, the pragmatic programmer, event based programming, analysis patterns, design patterns (GoF), OO methods ( foundation edition and Object-Oriented Methods: Pragmatic Considerations edition ), patterns of enterprise application architecture, refactoring (as was mentioned ), domain driven design,
Object-Oriented Software Construction,
Art of Computer Programming, The, Volumes 1-3,
Pattern-Oriented Software Architecture Volume 1
Object-Oriented Analysis and Design with Applications,
Working Effectively with Legacy Code,
Refactoring to Patterns, implementation patterns, How the Mind Works, The Language Instinct: How the Mind Creates Language, Pragmatic Thinking and Learning: Refactor Your Wetware , Domain-Specific Application Frameworks: Frameworks Experience by Industry, Don't Make Me Think! A Common Sense Approach to Web Usability, Object Solutions: Managing the Object-Oriented Project, Object Oriented Software Engineering: A Use Case Driven Approach , IBM Office Systems: Architectures and Implementations by Martin, Principles of Object-Oriented Analysis and Design, Object Oriented Analysis, Structured Analysis and System Specification, Practical Guide to Structured Systems Design, Designing Object-Oriented Software
maybe not 25 i was just throwing that number out there to show off
http://www.amazon.com/gp/registry/wishl ... P7FT2ER523
-
alex.barylski
- DevNet Evangelist
- Posts: 6267
- Joined: Tue Dec 21, 2004 5:00 pm
- Location: Winnipeg
Re: What is the essence of good software design
Again - As I've said, I totally advocate factoring. What I was saying is, that regardless of the refactoring that improvers readability/clarity/etc the LOC remain the same (or rather, increase). Therefor SLOC is not a useful metric for complexity.With 500 lines I am sure I could find code reuse but its not just about code reuse its about readability/clarity and context.
Re: What is the essence of good software design
This is a long thread to read the whole discussion in one sitting, but I read the first couple pages.
To answer the original question
"What is the essence of good software design?"
I would have to say that a simpler articulate answer is going to be my approach as opposed to a big list of technical characteristics.
1. Since software design consists of designing a user experience: It must be as clear and user friendly as possible.
2. It must be as robust and efficient as possible.
Since we're speaking on a theoretical level and not getting into the practicalities.
And I must say, Josh I've never read anything that makes more sense than the points you've made in this thread. Although I'm sure everybody has had some great things to contribute.
Also I really support Pytrims notion that abstractable code is extremely important especially for the long term.
To answer the original question
"What is the essence of good software design?"
I would have to say that a simpler articulate answer is going to be my approach as opposed to a big list of technical characteristics.
1. Since software design consists of designing a user experience: It must be as clear and user friendly as possible.
2. It must be as robust and efficient as possible.
Since we're speaking on a theoretical level and not getting into the practicalities.
And I must say, Josh I've never read anything that makes more sense than the points you've made in this thread. Although I'm sure everybody has had some great things to contribute.
Also I really support Pytrims notion that abstractable code is extremely important especially for the long term.