Open discussions on specific topics selected by the Software Working Group and selected from the list of SWG Topics For Discussion.
Writing Clean Code, moderated by Ya-Lan Yang
"Clean Code: A Handbook of Agile Software Craftsmanship" is a book written by Robert C. Martin, also known as "Uncle Bob", that emphasizes the importance of writing clean and maintainable code. The author explains how to write code that is easy to understand, modify, and extend, and provides guidelines and best practices for achieving these goals. The book also includes case studies and examples of real-world code, as well as discussions of common mistakes and how to avoid them. The discussion will be focusing on the first five chapters of this book: naming, functions, comments, and formatting.
Recording:
Slides: https://uofi.box.com/s/98n7kqj6cvfmu0gv1y1teglfovbsefkb
Attendees:
Ya;Lan Yang
Bing Zhang
Chen Wang
Rebecca Eveland
Jong Lee
Luigi Marini
Marcos Frenkel
Visu Monaharajan
Minu Mathew
Yong Wook Kim
Kate Arneson
Mike Bobak
Sandeep Puthanveetil Satheesan
Sara Lambert
Wendy Shan
In Kwon Choi
Lisa Yanello
Charles Blatti
Rashmil Panchani
Santiago Nunez-Corrales
Discussion:
Discussion of the book Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin (Uncle Bob). We'll be discussion
Meaningful Names
- Intention Revealing Names
- Avoid Disinformation
- Make Meaninful Distinction
- Pronounceable Names
- Class Names ( not a verb)
- Method should have a verb like DeletePage or Save
- Sandeep notes that the naming convention seems to be very long - I try to keep it descriptive, but short
- Rebecca notes that using general descriptive terms can be misinterpreted for something that you didn't mean.
- Santiago notes: It depends on project conventions and the kinds of problems being solved as well. A good test is this: can you at least understand the intent of the code without having to resort to comments? Six months after writing it
- Jong notes that class name does not have to be repeated. Discussion followed about naming conventions
Functions
- A function should be small and tell a story
- Do one thing (except switch)
- Have less than three arguments
Comments
- Good comments include legal documents, informative comments, clarification and TODO comments, warning of consequences
- Minu mentions docstrings
- Templates
- Mike Bobak notes: https://docs.python.org/3/library/doctest.html
- Luigi notes: If you are adding a lot of comments, it may mean you need to rewrite the code!
- Writing codes from many contributors need to have consistent code.
- Point people to the interesting part of the code, which is usually about 10%.
- Rashmil is a big fan of formatting/parameters
- Santiago notes: Another book I really enjoyed was “Structure and Interpretation of Computer Programs” by Abelson and Sussman. Open book version accessible at: https://web.mit.edu/6.001/6.037/sicp.pdf
- GitHub Education allows access to all kinds of publications!
- Sara notes that refactoring can be very powerful if you can extract a method.
Links mentioned in this Round Table:
Best Practices Handbook: https://github.com/ncsa/software-development-handbook
If you are interested in contributing to a Round Table, please see these links:
Round Table Google Sheet: https://docs.google.com/spreadsheets/d/1kbgO6sIb_4eLugfSVKQNCTXdaKp1R6m0RDczPTsUAoQ/edit#gid=0 Every one should have edit permission.