Did you ever copy & paste your source-code from your IDE or editor into an LMR article
and found out that all syntax highlighting and formatting is gone?
Did you ever tried to help a fellow LMRian with his software problem
but struggled with the readability of the source-code in a sans-serif font with huge word wraps?
In this article you learn how you can copy & paste your source-code and keep all the formatting.
..but first: Let me argue why this is important. If you know why then scroll down to the screen shots to see how.
Readability is Understandability
Whenever you write source code, you know that you are going to read the code several times more than write. Therefore it is worth to pay attention on how this code is presented to you.
You program this code, refactor it to a pattern, refactor it to better testability, add a new skill, refactor it to be more domain specific, refactor it to more isolation and modularisation and add a new quality so that every change is transactional or a watchdog for realtime control.
In between all this refactorings you read the code.
You seek through it on the mission to find that bug. Or you read it because someone else has wrote it, and you try to understand it. Try to find the concepts behind it. The concepts of the system, the abstractions and the data, the mechanics and domain it is targeted to.
You want to know what it does and how.
Also you may focus on function names and types in C or on classes and methods in Java. In these general purpose languages you may want to see the signatures and types and what this signatures and types imply i.e. a void or a @CheckForNull or a null or int or TheBestReturnValueEver or @throws TheWorstExceptionEver.
And you might use code density to express what belongs together. Write the struct so that you see on one glimpse that this is a data unit. One expression for something in the system.
This code density is something you add to your code as a concept.
It's intentional. Formatting is intentional.
What is intentional we shall not loose. The language specific formatting shall not disapear just because we post it online or here at LMR.
Again, most of the todays IDEs and source-code editors have language features that i.e. highlight the Java code in the Java-way and C in the C-way. Every language has it's own keywords and own formatting guidelines and the todays editors support that. Editors format the code to visually dictinct between language keywords, idioms and your hand crafted code.
Not that you can't work with un-formatted code... we've all done and do that - work with bare metal Notepad as an example. It's that having a well formatted code that is readable increases the understandability. And this quality-attribute is essential in complex software like a lot of our robots here at LMR.
Principle of Least Astonishment
The more our code differs from the common formatting guidelines the more astonishment we introduce to the reader. Did you ever used Word to make some fancy formatting with your code? I.e. use red scary font for exception handling code, green fat code for the code you are most proud of and underline the code that smells?
Shure someone has done that. But most of us don't. So stick to the principle of the least astonishment and format the code as exact as possible to the language formatting guidelines. Mind the gap.
Automatic HTML Generation
To format your code go ahead and use a tool that translates your source-code directly to HTML. Don't try to hand-format your code. There is good tool support for this task. Let a software do the job.
Here I introduce two simple ways to get formatted code.
From Your Editor to the LMR Text-Box
We now copy HTMLized code from somewhere into the LMR editor.
If you have the Arduino IDE you get this HTML export for the C code that generates colored and formatted HTML that looks exactly as in the editor. Klick [Edit] -> [Copy as HTML]. The HTML code is copied directly into the clipboard. Ready to paste it into the LMR editor. To paste it open the editor and click on HTML. Paste it where you want it... or in the very end.
Here a sample that gives the impression of the difference. Some might not bother. But some bother this nuance.
This is what you get from the Arduino IDE.
If your IDE does not support this feature go ahead and use one of the online conterters out there.
One converter I sometimes use is this one. Copy the code from your editor and paste it into the text-box from the converter. Select the language you have i.e. C and click ok. This is what you get.
And don't forget to add the line numbers if you ask for help in your code.
Happy coding. Happy reading.
Further Readings
Sidecomment
This article's profile image shows a programming style that is used i.e. to configure an object or a task. The code in the picture is intended to look like a phrase in the domain language. Here the readability is a first class citizen. The semantic model is visible and makes it understandable. It's a internal DSL using Method Chaining to make it fluent and explorative (if you have code completion).
