Talks
Speakers
Events
Topics
Sign in
Home
Talks
Speakers
Events
Topics
Leaderboard
Use
Analytics
Sign in
Suggest modification to this talk
Title
Description
Self-documenting code is a pipe dream. TDD (or BDD) is not the panacea of testing. In the pursuit of test coverage we've forgotten what really matters: getting things done. Lets talk about putting documentation and testing into their proper place. Tools that ease maintenance, help other developers join a project, and reduce bugs. I'm going to go over lessons learned in writing, maintaining, and introducing new developers to 20,000 lines of code. Specifically, how we are testing, documenting, and refactoring our code to stay sane, make the team happier, and get more done. Help us caption & translate this video! http://amara.org/v/FGah/
Date
Summarized using AI?
If this talk's summary was generated by AI, please check this box. A "Summarized using AI" badge will be displayed in the summary tab to indicate that the summary was generated using AI.
Show "Summarized using AI" badge on summary page
Summary
Markdown supported
In the talk "Delicious Controversy: Docs & Tests" by Thomas Meeks at Rails Conf 2013, the speaker challenges the conventional wisdom around self-documenting code and test-driven development (TDD), advocating for a practical approach to documentation and testing in software development. Meeks reflects on experiences gained while working on a project called Code School, which involved managing a codebase of over 27,000 lines across multiple developers. **Key Points:** - **Documentation Myths:** Meeks begins by criticizing the notion of self-documenting code, arguing that it is unrealistic. He explains that while clear method naming can indicate functionality, it often fails to convey crucial context that new team members may require to understand the system's workings. - **Spec Documents vs. Specs:** The speaker shares his viewpoint that specs cannot substitute for proper documentation. He highlights that while integration tests (specs) serve a purpose from a user perspective, they do not effectively communicate programmatic details necessary for understanding the code's functionality without exhausting effort. - **Approach to Documentation:** He advocates for documenting code as it is written to avoid the burden of recalling array logic and other details complacently at a later date. Meeks suggests documenting public methods succinctly, focusing on what parameters the method requires, what it does, and its potential side effects. - **Critique of Unit Testing and TDD:** Meeks critiques unit tests, categorizing them as often resulting in over-engineering and unnecessary maintenance. He emphasizes integration tests as a solution to ensure that features work as intended and encourages adoption of a holistic approach to testing that allows developers to consider the full stack. - **Real-World Case Studies:** Meeks utilizes practical examples, such as subscription management, to underscore how improved documentation and integration testing can lead to smoother development processes. He illustrates how using service classes and presenters can create cleaner, more maintainable architectures while improving the clarity and robustness of tests. **Conclusions:** The primary takeaway of Meeks' talk is the importance of prioritizing practical strategies over strict adherence to TDD and the myths of self-documenting code. By fostering an understanding of core principles and iterating on documentation practices, teams can enhance developer happiness, reduce technical debt, and make significant strides in productivity. Meeks emphasizes that happy programmers lead to more effective team performance, arguing that operational efficiency should come from streamlined code management, not overwhelming documentation or testing burdens. He concludes by encouraging developers to determine what techniques work best for them, promoting a culture of flexibility and critical thinking in software engineering.
Suggest modifications
Cancel
