GNOME Bugzilla – Bug 747997
programming guidelines: add some book references for writing good code
Last modified: 2015-04-18 17:37:52 UTC
See the attached patch. I'm not sure if a short description should be written for each book.
Created attachment 301744 [details] [review] programming-guidelines: add book references for writing good code When possible, the link is the official web page for the book. As a fallback, a link to wikipedia (if a page exists) or Amazon. If only one book should be chosen for "writing good code" (the subject of the page), it should be Code Complete IMHO. It covers a wide range of subjects, from single lines of code to the general architecture of big programs, with introductory chapters on other topics like refactoring, debugging, performances, etc. The Refactoring and Design Patterns books are also the references for those subjects, which are important for code quality and maintainability. Finally, Object-Oriented Design Heuristics is also a really good book, that contains many guidelines for writing OO code. It's IMHO a more important book than Design Patterns, although the latter is more well-known. The guidelines explained in the book apply to every OO code, even for a small codebase. On the other hand some design patterns are useful only for big codebases. Since every software must begin by a small codebase, it's better to apply OO best-practices from the start.
Review of attachment 301744 [details] [review]: What’s the motivation for adding this? i18n-wise, this is an interesting one, since those books might not be available in other languages. Maybe add a translation comment advising translators to pick good books in their own languages, or to stick with the English ones if there is no alternative?
(In reply to Philip Withnall from comment #2) > What’s the motivation for adding this? I think code quality and maintainability is an important subject. We can learn by experience and code reviews, but we can also learn a lot - and more quickly - by reading books. > i18n-wise, this is an interesting one, since those books might not be > available in other languages. Maybe add a translation comment advising > translators to pick good books in their own languages, or to stick with the > English ones if there is no alternative? If a translation of the book is available, yes, why not. I'm not sure those subjects are covered in many languages though. For more advanced stuff in computer science, English is the de facto language… The Additional Materials page doesn't contain comments for translators: https://git.gnome.org/browse/gnome-devel-docs/tree/programming-guidelines/C/additional-materials.page But it contains descriptions of the books.
Opinion from an experimented translator. Usually in such cases, we: * replace references by their translations when available * keep the originals for the ones that don't have a translation and add something a comment in parentheses such as "in English", or "no translation available to this day" * add some relevant existing material in the target language (i.e. in French I would add books that have been written in French and are not translation from English books)
Review of attachment 301744 [details] [review]: Hmm, OK. I see no harm in adding this, on the understanding that if better CC-licenced resources on coding best practices are written or published, we remove these links and link to those instead. Please commit with the suggested change below. ::: programming-guidelines/C/writing-good-code.page @@ +141,3 @@ + </p></item> + <item><p> + <link href="http://www.amazon.com/Object-Oriented-Design-Heuristics-Arthur-Riel/dp/020163385X/"> Please change this to the GNOME referral link for Amazon.
Done: https://git.gnome.org/browse/gnome-devel-docs/commit/?id=4e0347f53a873e101fc862f90b712b16a1710d32 For the Amazon link, it's now: http://astore.amazon.com/gnomestore-20/detail/020163385X