{"id":1751,"date":"2016-12-22T16:07:56","date_gmt":"2016-12-22T15:07:56","guid":{"rendered":"https:\/\/blog.mi.hdm-stuttgart.de\/?p=1751"},"modified":"2023-06-07T15:24:04","modified_gmt":"2023-06-07T13:24:04","slug":"snakes-exploring-pipelines-a-system-engineering-and-management-project-4","status":"publish","type":"post","link":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/2016\/12\/22\/snakes-exploring-pipelines-a-system-engineering-and-management-project-4\/","title":{"rendered":"Snakes exploring Pipelines – A \u201cSystem Engineering and Management\u201d Project"},"content":{"rendered":"

Part 3: Coding Guidelines<\/h3>\n

This series of blog entries describes a student project focused on developing an application by using methods like pair programming, test driven development and deployment pipelines. <\/strong><\/p>\n

\"\"<\/a><\/p>\n

An important part of any professional software development process (like ours \ud83d\ude00 ) are coding guidelines and methodologies, so we\u2019ll deal with these in today\u2019s blog entry. A fancy system we learned about in the course was the 12 factor methodology. It is mainly applicable for web-based, software as a service (SaaS) applications and defines high-level aspects an application should follow in order to remain robust and maintainable throughout its lifecycle.<\/p>\n

<\/p>\n

The 12 factors, including detailed descriptions can be found on https:\/\/12factor.net\/<\/a> . While our current project is not exactly web based, it should be interesting to take a look at the factors which are applicable to our game:<\/p>\n

I. Codebase: One codebase tracked in revision control, many deploys
\nWhile our only deploy was basically the version of our code we actively developed, we used Git for tracking the code, respectively GitHub as a repository, as explained in an earlier entry.<\/p>\n

II. Dependencies: Explicitly declare and isolate dependencies
\nThanks to Gradle, we got this point covered, as all dependencies are listed in the build.gradle file. An example dependency in our case is JUnit. Gradle also automatically includes dependencies in its build process.<\/p>\n

III. Config: Store config in the environment
\nIn our project, the configuration for the game (for example the snake\u2019s speed or the amount of food available) is stored in the file config.properties, which is part of the project folder and thus separated from the code. However, we didn\u2019t store configs in the environment, apart from paths to Gradle etc in the initial setup. Our jar file creates the config file in the same directory, the first time it is executed, or if the existing config file is invalid.<\/p>\n

IV. Backing services: Treat backing services as attached resources
\nOur game currently does not use any backing services\/ external resources. However, a good example for such a service could be a webserver with a database which stores high-scores from different users.<\/p>\n

V. Build, release, run: Strictly separate build and run stages
\nAgain, Gradle saves the day by allowing us to automate our builds and include the config into the resulting jar-file.<\/p>\n

The points VI through IX are specific to web based services and not applicable to our project, unfortunately \ud83d\ude41<\/p>\n

X. Dev\/prod parity: Keep development, staging, and production as similar as possible<\/p>\n

This is quite an interesting factor, directly related to continuous deployment:<\/p>\n

\"Source:<\/a><\/p>\n

Due to our group having only three people, the gap between developers and deployers tends to be quite small. By using Gradle (and Jenkins, later on) it would be theoretically possible release a new build after each newly developed feature.<\/p>\n

XI. Logs: Treat logs as event streams
\nWriting events to stdout would be no problem in our case, however this factor additionally assumes a logging framework collecting these event outputs and writing them to a log file.<\/p>\n

XII. Admin processes
\nNot really applicable in our case as well, since we don\u2019t need any admin privileges for our game.<\/p>\n

As mentioned before, many of the 12 factors are only really applicable to web-based services, so let\u2019s take a look at some more general best principles for software development we tried to follow in our snakey project. (Many of the following ones can be found on http:\/\/clean-code-developer.de<\/a> , which is a german site, unfortunately, but fret not, we\u2019ll translate the important stuff here.)<\/p>\n

One of the most commonly cited principles of clean code is \u201cDon\u2019t repeat yourself\u201d, basically meaning not to duplicate existing code, because this can very easily lead to errors spreading throughout the code base and inconsistencies due to fixes for those errors, or other changes to the code.<\/p>\n

Another well-known principle is \u201cKISS\u201d (Keep it simple, stupid): Code should be simple, easily understandable and follow a clear structure. Always favour an easy solution in order not to unnecessarily complicate code. It should be possible to understand and work with the code relatively fast – an important tool here are comments, which are often neglected. This is especially important in the age of continuous deployment, where bugs have to be fixed ASAP.<\/p>\n

\u201cDon\u2019t optimize prematurely\u201d is certainly in the top-3 of famous best practices as well. In most cases, the primary goal should be to produce readable code. Optimized code is often not readable. A hardware update may render your optimization useless and a waste of time (and money.<\/p>\n

Especially when talking about OO-development, \u201cFavour Composition over Inheritance\u201d is often cited as composition is more flexible, testable and extensible than inheritance (you do know the difference, do you?).<\/p>\n

Besides those fairly known principles, we also found lesser known ones, like the \u201cIntegration Operation Segregation Principle\u201d (IOSP). It states that functions containing logic and operations should be separated from functions calling other functions. This results in shorter, easier to test code.<\/p>\n

For achieving a similar result, \u201cSingle Level of Abstraction\u201d can be used. In a given method, all functions should belong to the same degree of abstraction. Such code is easier to read and understand as well.<\/p>\n

Compatible herewith is the \u201cSingle Responsibility Principle (SRP)\u201d, which recommends to focus on a single responsibility at a time, i.e. one class or function should have exactly one clearly defined task. In case of changes to the code, it is obvious which classes have to be adapted.<\/p>\n

\u201cSeparation of Concerns\u201d (SoC) in turn is linked to the \u201cSingle Responsibility Principle\u201d. Classes that have a single responsibility can still have multiple purposes, like logging, tracing, caching, persistency and so on. These objectives need to be separated into different methods or, if this is not possible, be clearly marked. In the best case each component focuses on one task, which leads to better testability and understandability.<\/p>\n

\"As<\/a>
As a visualization of badly developed code: Spaghetti-snakes<\/figcaption><\/figure>\n

\u201cSource Code conventions\u201d: Code is read more often than it is written. Therefore we need conventions that facilitate reading and understanding of new code. The main aspects that need to be considered are naming conventions and commenting. Agree on a consistent naming for variables, classes and methods. For example, we used underscore separation for our snake variables. No individual styles of developers need to be trained.
\nIf you want to follow this path even further, you can aim for good code which does not need any comments. Mid-level quality code would have some comments to explain some complex dependencies in short. (In our snake project we only have a few comments \ud83d\ude00 ) As a guideline: Before commenting three lines of code, extract them in a separate method with a speaking method name.<\/p>\n

Some more assorted practices we found during our research:<\/p>\n

\u201cScout\u2019s honor: Always leave a place in a better state than you found it.\u201d -> Good developers leave code in a better state than in the state they found it in.<\/p>\n

Root Cause Analysis: Healing symptoms is a fast treatment. However, in the long run, it\u2019s more effort. Therefore, always solve problems by detecting its root cause and dealing with it directly. You can use this method simply by asking yourself at least five times \u201cWhy?\u201d.<\/p>\n

Use a version control system: Always use a version control system like Git, Mercurial or Subversion. This relieves the fear of breaking something when coding – the code can be reversed and you can learn a lot from mistakes.<\/p>\n

Simple refactoring patterns: For code refactoring, use known patterns like those described by Martin Fowler. Their use cases highlight weaknesses in your code and encourage their usage because of proven additional value. For example start by renaming cryptical variables and methods into understandable easily readable code. Most of the refactoring has to be done manually. Some IDEs offer tools to support you.<\/p>\n

\"\"<\/a><\/p>\n

Reflect on your progress: Implementing the Clean Code principles in your daily coding activities can be a long process. Therefore it is necessary to plan and progress in small steps and ask yourself at the end of each day: \u201cHow did I do my work?\u201d The resulting answers can be very helpful for self-improvement and motivation and lead to a better learning curve.<\/p>\n

Issue Tracking: The snake brain sometimes behaves like a sieve. In order not to forget issues, write them down. Prioritize issues and solve them one after the other. Tools can help here as well. For our project, we used waffle.io to track issues and tasks.<\/p>\n

Automated integration testing: Do integration tests. It is a repetitive work so automate it with our favourite tools: Git and Jenkins.<\/p>\n

Reviews: Showing your code to another developer can be very helpful for feedback and early error recognition (e.g. if the code is not matching the user requirements). Pair programming and code reviews are methods to escape the tunnel vision problem.<\/p>\n

Read, Read, Read: Reading educates. Reading our blog is a good start. To keep yourself updated with the development of new techniques and it is recommended to read at least 6 books, papers or technical articles on subjects concerning your work per year.<\/p>\n

Of course, there are many more code guidelines to catch up, if you\u2019re interested in the topic. For Java, see:
\nhttp:\/\/www.torsten-horn.de\/techdocs\/java-codingconventions.htm<\/a>
\nhttp:\/\/www.javapractices.com\/home\/HomeAction.do<\/a><\/p>\n

For general advice:
\n(only in German: http:\/\/clean-code-developer.de\/)
\nand of course the bestseller on this topic: Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin (including some mystical sounding guidelines like the \u201cLaw of Demeter\u201d)<\/p>\n

One last aspect remains for this long and winding blog entry: Static code analysis
\nFor Eclipse there are several static code analysis tools which helped us finding stupid mistakes in our code like dead code, duplicate code or unnecessary assignments and other qualitative weaknesses (bad smells – please open the windows for some fresh air here). For eclipse we highly recommend FindBugs, Checkstyle and PMD.
\nThey are all easy to use and Open Source, so install them via the Eclipse Marketplace and give them a try.<\/p>\n

Don\u2019t forget to like and subscribe.<\/p>\n","protected":false},"excerpt":{"rendered":"

Part 3: Coding Guidelines This series of blog entries describes a student project focused on developing an application by using methods like pair programming, test driven development and deployment pipelines. An important part of any professional software development process (like ours \ud83d\ude00 ) are coding guidelines and methodologies, so we\u2019ll deal with these in today\u2019s […]<\/p>\n","protected":false},"author":58,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[1,22,651,2],"tags":[],"ppma_author":[698],"class_list":["post-1751","post","type-post","status-publish","format-standard","hentry","category-allgemein","category-student-projects","category-system-designs","category-system-engineering"],"aioseo_notices":[],"jetpack_featured_media_url":"","jetpack-related-posts":[{"id":1758,"url":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/2017\/01\/12\/snakes-exploring-pipelines-a-system-engineering-and-management-project-5\/","url_meta":{"origin":1751,"position":0},"title":"Snakes exploring Pipelines – A \u201cSystem Engineering and Management\u201d Project","author":"Yann Loic Philippczyk","date":"12. January 2017","format":false,"excerpt":"Part 4: Jenkins and Wrap Up This series of blog entries describes a student project focused on developing an application by using methods like pair programming, test driven development and deployment pipelines. Our first blog entry for this year will at the same time be the final one for this\u2026","rel":"","context":"In "Allgemein"","block_context":{"text":"Allgemein","link":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/category\/allgemein\/"},"img":{"alt_text":"","src":"https:\/\/i0.wp.com\/blog.mi.hdm-stuttgart.de\/wp-content\/uploads\/2017\/01\/jenkins_code-1.png?resize=350%2C200&ssl=1","width":350,"height":200,"srcset":"https:\/\/i0.wp.com\/blog.mi.hdm-stuttgart.de\/wp-content\/uploads\/2017\/01\/jenkins_code-1.png?resize=350%2C200&ssl=1 1x, https:\/\/i0.wp.com\/blog.mi.hdm-stuttgart.de\/wp-content\/uploads\/2017\/01\/jenkins_code-1.png?resize=525%2C300&ssl=1 1.5x"},"classes":[]},{"id":1711,"url":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/2016\/11\/26\/snakes-exploring-pipelines-a-system-engineering-and-management-project\/","url_meta":{"origin":1751,"position":1},"title":"Snakes exploring Pipelines – A \u201cSystem Engineering and Management\u201d Project","author":"Yann Loic Philippczyk","date":"26. November 2016","format":false,"excerpt":"Part 0: Introduction This series of blog entries describes a student project focused on developing an application by using methods like pair programming, test driven development and deployment pipelines. Once upon a time, which was about one and a half months ago, an illustrious group of three students found together,\u2026","rel":"","context":"In "Allgemein"","block_context":{"text":"Allgemein","link":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/category\/allgemein\/"},"img":{"alt_text":"A python. (Because snakes. Not the language.) Source: https:\/\/rashmanly.files.wordpress.com\/2008\/10\/1439659.jpg","src":"https:\/\/i0.wp.com\/blog.mi.hdm-stuttgart.de\/wp-content\/uploads\/2016\/11\/0_1-300x300.jpg?resize=350%2C200&ssl=1","width":350,"height":200},"classes":[]},{"id":1740,"url":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/2016\/12\/09\/snakes-exploring-pipelines-a-system-engineering-and-management-project-3\/","url_meta":{"origin":1751,"position":2},"title":"Snakes exploring Pipelines – A \u201cSystem Engineering and Management\u201d Project","author":"Yann Loic Philippczyk","date":"9. December 2016","format":false,"excerpt":"Part 2: Initial Coding This series of blog entries describes a student project focused on developing an application by using methods like pair programming, test driven development and deployment pipelines. Onwards to the fun part: The actual coding! In this blog entry, we will focus on test-driven development. Like we\u2026","rel":"","context":"In "Allgemein"","block_context":{"text":"Allgemein","link":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/category\/allgemein\/"},"img":{"alt_text":"A snake looking forward towards the next task, after having performed several incremental test-driven programming iterations Source: http:\/\/cdn1.arkive.org\/media\/0F\/0F35A02E-58A1-408B-B259-88C1E319B1C3\/Presentation.Large\/Curl-snake-coiled.jpg","src":"https:\/\/i0.wp.com\/blog.mi.hdm-stuttgart.de\/wp-content\/uploads\/2016\/12\/entry2-snake.png?resize=350%2C200&ssl=1","width":350,"height":200,"srcset":"https:\/\/i0.wp.com\/blog.mi.hdm-stuttgart.de\/wp-content\/uploads\/2016\/12\/entry2-snake.png?resize=350%2C200&ssl=1 1x, https:\/\/i0.wp.com\/blog.mi.hdm-stuttgart.de\/wp-content\/uploads\/2016\/12\/entry2-snake.png?resize=525%2C300&ssl=1 1.5x"},"classes":[]},{"id":1729,"url":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/2016\/12\/08\/snakes-exploring-pipelines-a-system-engineering-and-management-project-2\/","url_meta":{"origin":1751,"position":3},"title":"Snakes exploring Pipelines – A \u201cSystem Engineering and Management\u201d Project","author":"Yann Loic Philippczyk","date":"8. December 2016","format":false,"excerpt":"Part 1: Tool Setup This series of blog entries describes a student project focused on developing an application by using methods like pair programming, test driven development and deployment pipelines. Welcome to the next part our project, on its way to become the Snake game with the very best underlying\u2026","rel":"","context":"In "Allgemein"","block_context":{"text":"Allgemein","link":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/category\/allgemein\/"},"img":{"alt_text":"","src":"https:\/\/i0.wp.com\/blog.mi.hdm-stuttgart.de\/wp-content\/uploads\/2016\/12\/blue-krait.jpg?resize=350%2C200&ssl=1","width":350,"height":200,"srcset":"https:\/\/i0.wp.com\/blog.mi.hdm-stuttgart.de\/wp-content\/uploads\/2016\/12\/blue-krait.jpg?resize=350%2C200&ssl=1 1x, https:\/\/i0.wp.com\/blog.mi.hdm-stuttgart.de\/wp-content\/uploads\/2016\/12\/blue-krait.jpg?resize=525%2C300&ssl=1 1.5x"},"classes":[]},{"id":5262,"url":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/2019\/02\/26\/reproducibility-in-ml\/","url_meta":{"origin":1751,"position":4},"title":"Reproducibility in Machine Learning","author":"Pascal Fecht","date":"26. February 2019","format":false,"excerpt":"The rise of Machine Learning has led to changes across all areas of computer science. From a very abstract point of view, heuristics are replaced by black-box machine-learning algorithms providing \"better results\". But how do we actually quantify better results? ML-based solutions tend to focus more on absolute performance improvements\u2026","rel":"","context":"In "Allgemein"","block_context":{"text":"Allgemein","link":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/category\/allgemein\/"},"img":{"alt_text":"","src":"","width":0,"height":0},"classes":[]},{"id":2143,"url":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/2017\/03\/08\/of-apache-spark-hadoop-vagrant-virtualbox-and-ibm-bluemix-services\/","url_meta":{"origin":1751,"position":5},"title":"Of Apache Spark, Hadoop, Vagrant, VirtualBox and IBM Bluemix Services – Part 1 – Introduction","author":"bh051, cz022, ds168","date":"8. March 2017","format":false,"excerpt":"As part of the lecture \u201cSystem Engineering and Management\u201d in the winter semester 2016\/17, we run a project with Apache Spark and the Apache Hadoop Ecosystem. In this article series firstly we want to introduce Apache Spark and the Apache Hadoop Ecosystem. Furthermore we want to give an overview of\u2026","rel":"","context":"In "Student Projects"","block_context":{"text":"Student Projects","link":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/category\/student-projects\/"},"img":{"alt_text":"","src":"","width":0,"height":0},"classes":[]}],"jetpack_sharing_enabled":true,"authors":[{"term_id":698,"user_id":58,"is_guest":0,"slug":"yp007","display_name":"Yann Loic Philippczyk","avatar_url":"https:\/\/secure.gravatar.com\/avatar\/1417bdd3183c4e56c15d9942de2b27a306ca0e2e6bbd14669933523fd781d806?s=96&d=mm&r=g","0":null,"1":"","2":"","3":"","4":"","5":"","6":"","7":"","8":""}],"_links":{"self":[{"href":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/wp-json\/wp\/v2\/posts\/1751","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/wp-json\/wp\/v2\/users\/58"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/wp-json\/wp\/v2\/comments?post=1751"}],"version-history":[{"count":1,"href":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/wp-json\/wp\/v2\/posts\/1751\/revisions"}],"predecessor-version":[{"id":1756,"href":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/wp-json\/wp\/v2\/posts\/1751\/revisions\/1756"}],"wp:attachment":[{"href":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/wp-json\/wp\/v2\/media?parent=1751"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/wp-json\/wp\/v2\/categories?post=1751"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/wp-json\/wp\/v2\/tags?post=1751"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/blog.mi.hdm-stuttgart.de\/index.php\/wp-json\/wp\/v2\/ppma_author?post=1751"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}