The Pragmatic Programmer - The Evils of Duplication

Reusable Code

The importance of making code reusable cannot be overstated. Alan Underwood emphasizes that if code isn't easy to reuse, it simply won't be reused, leading to inefficiencies and duplicated efforts. However, the team debates the pitfalls of centralizing utility routines, with Michael Outlaw arguing against it, fearing it would become a dumping ground for miscellaneous code 1. Joe Zack suggests that while a central repository can be useful, it often leads to bloated and hard-to-navigate codebases 2.

I would rather have a single-purpose package than a utility package with 9 billion things I don't care about and will never use.

--- Alan Underwood

The consensus is that while reusability is crucial, it must be balanced with maintainability and clarity.

   

Effective Documentation

Effective documentation is a cornerstone of pragmatic programming. Joe Zack and Alan Underwood express frustration with poor documentation, which often lacks practical examples and clear instructions. Michael Outlaw highlights the issue of untrustworthy comments, which can be more detrimental than no comments at all 3. They agree that documentation should include numerous examples to be truly useful 4.

Show me how it's used. I get so mad when I go to some documentation that a company's written and there's no example.

--- Alan Underwood

The team stresses that good documentation should be both comprehensive and practical, aiding developers in understanding and utilizing the code effectively.

   

Code Generation

Code generation offers both benefits and challenges in software development. Michael Outlaw questions whether generating code from metadata is an outdated concept, while Alan Underwood argues that it still has its place, especially in specific use cases like ORM 5. They discuss the efficiency of using code generators to build code from a common set of metadata, which can reduce duplication and ensure consistency 6.

I definitely conceptually like this idea because you get consistency from your code.

--- Michael Outlaw

Ultimately, the team acknowledges that while code generation can streamline development, it must be implemented thoughtfully to avoid complexity and maintain flexibility.