A proposed add-on for Software Engineering courses

Mircea Cadariu
Aug 9, 2016 · 6 min read

For Software Engineering students, the path to mastery of the field is a lot like that of chess. Students must transition from mastering the rules — knowing the allowed moves of the pieces on the board — to being able to apply winning strategies based on principles. In software education, the transition is from programmer to engineer; from writing the first working program to balancing trade-offs to arrive at the best technical solution.

Photo by Maarten van den Heuvel

Tool-based feedback mechanisms support rapid learning. For the first learning stage, which is about the consistent application of the rules, the software compiler is key. It provides unambiguous feedback regarding the syntactical correctness of the program according to the programming language rules. As the student progresses and needs to start internalizing the principles, identifying tool support becomes less clear-cut. It seems that an apprenticeship period with an experienced practitioner is irreplaceable.

A way of working for future careers

At SIG, we seek to alleviate this state of affairs using the Better Code Hub. This newly-built software platform enables users to check the compliancy of software systems with the 10 guidelines for Maintainability introduced in the Building Maintainable Software book. In order to determine compliancy, it extracts structural code-level metrics and compares them with benchmark-calibrated thresholds for each guideline. If users write Better Code Hub-compliant code, it means that they code like the best developers in the industry (4 stars on the SIG scale).

“The gap between the best software engineering practice and the average practice is very wide — perhaps wider than in any other engineering discipline. A tool that disseminates good practice would be important.”

Fred Brooks

In the context of typical semester-long or year-long student projects Better Code Hub supports learning a way of working. It resembles the Inspect and Adapt tenets of Scrum. Students write some code for the course deliverables, then they scrutinize it against the 10 guidelines before writing new code. If there are violations, they discuss them and devise a plan to become compliant. When compliancy is achieved they continue to work on the system they are developing.

By diligently following this process, students accumulate valuable first-hand experience which they will take with them in their future careers in the software industry. They will become accustomed to the art of balancing writing new code with reducing technical debt, a necessary skill to have, given the current need for reliable and maintainable software. While learning, they will also get a taste of the pleasure of developing software in a high-quality and maintainable code base and hopefully seek to recreate these conditions when they start their career.

Photo by Florian Klauer

Better Code Hub — how does it work?

For short feedback loops, Better Code Hub works in tandem with GitHub. We have seen that students increasingly use GitHub repositories for holding the source code of the app they are building to satisfy the course requirements. On Better Code Hub, upon clicking the “Sign in” button students will be prompted with a page from GitHub asking for read-only permission to be granted. This is to allow the platform to retrieve source code from their existing GitHub repositories. After permission is granted, they are ready to start an automated analysis for one of their repositories.

After the analysis is done, students will be presented with a results page where they can understand their overall compliance with the guidelines and browse through the findings. For example, they receive prioritized action items — Refactoring candidates — for each guideline. Depending on the guideline, the refactoring candidates are units (e.g. Java methods), modules (e.g. Java classes), or components (e.g. Java packages) which should be improved. Students will still receive refactoring candidates even if they are compliant. This is because a compliant system does not reflect a perfect system, but reflects whether a system is rated with 4 stars on the SIG scale.

Analyzing Better Code Hub itself

Clicking on either one of the proposed refactoring candidates in the list will open up a pop-up which will help students to locate the violation in the source code. They can then diagnose the issue and think about how to structurally fix it.

“Number one in the stink parade is duplicated code.”

Martin Fowler

As an example, violations of Write Code Once (sets of modules which contain more than 6 lines of duplicated code) can be traced in the source code they have written by observing the highlighted block:

Code Duplication

Students don’t need to fix every Better Code Hub violation. Before jumping in and eagerly fixing a specific violation in a sub-optimal fashion, an analysis step is in order. They will take into account aspects such as the rate of change of the duplicated blocks, and if unifying them represents a real abstraction that can stand on its own feet. Better Code Hub uses a benchmark-calibrated measurement model under the hood. Therefore, for compliancy, some level of textual duplication is permitted. This accounts for the presence of textual duplication in systems that does not represent a true quality deficiency.

“It seems to me that some programmers see themselves as Terminators: out to eliminate all code duplication with extreme prejudice; sometimes, perhaps, without even considering the trade-offs involved. Every time you remove duplicated code, you add a level of indirection, and as you’ve probably heard before, all problems in computer science can be solved by another level of indirection, except for the problem of too many levels of indirection.”

Mark Seemann

The guidelines cover the most important aspects of a code base when it comes to maintainability, from the code level up to high-level architecture. For the latter, students can make use of code visualizations such as dependency graphs, as is the case for the findings related to the Couple Architecture Components Loosely guideline:

Component-level dependencies in Better Code Hub’s bundle graph

Visualizing the relationships between components enables students to reason about the collaborations that happen in the system and how potential future change impacts them. They can analyze the various levels of stability of the components they introduced in the system. If many changes are expected, then it is better to depend on abstractions, and not on volatile concrete implementations. This exercise will be very useful for them when later designing software systems which have to cope with change to meet market demands.

Rewarding students for writing future-proof code

Gamification is gaining more and more traction in higher education programs due to its many benefits. We think that Better Code Hub can fit nicely in bonus system schemes for Software Engineering courses as a component of the gamified course. Balancing writing new code for functionality while keeping the code future-proof will be rewarded by higher productivity later in their industry careers, therefore it should be rewarded by bonus points counting to the final grade for courses of a Software Engineering curriculum.

Photo by Juan Ramos

Some references

In the Netherlands, Better Code Hub has been used for courses at Delft University of Technology and University of Groningen.

Get in touch!

Students, by regularly checking their work according to the 10 guidelines that have been found to be applicable industry-wide, will ease their transition from rules to principles as in the chess analogy. Becoming familiar with these concepts as soon as possible in their learning path will pay off in the future. We hope that through the Better Code Hub, we can make learning the principles of software development more enjoyable and interactive.

We look forward to hearing from you, at bettercodehub@sig.eu. Let us know if you would like to add this to your course, or just tell us what you think about our proposed approach.

Write BetterCode

The Definition of Done for Product Quality: Improve what Matters with https://bettercodehub.com

Thanks to Rob van der Leek

Mircea Cadariu

Written by

Software Developer @sig_eu / @mcadariu

Write BetterCode

The Definition of Done for Product Quality: Improve what Matters with https://bettercodehub.com

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade