Last year I watched a YouTube video about “no comment code” which, to me, sounded like a terrible idea.\nA quick web search shows that not commenting code has it’s proponents. Let’s not get into that right now.<\/p>\n\n\n\n
While I didn’t agree with the video as a whole I did like one specific idea:<\/p>\n\n\n\n
\nUse types, rather than comments, to show what data is required.<\/p>\n<\/blockquote>\n\n\n\n
Actually, that one thing sounds kinda great.<\/p>\n\n\n\n
Instead of:<\/p>\n\n\n\n
\/\/ Duration is measured in seconds.\nvoid Sleep(float duration);<\/pre><\/div>\n\n\n\nYou can have:<\/p>\n\n\n\n
void Sleep(std::chrono::duration duration);<\/pre><\/div>\n\n\n\nThe first requires a comment so you know how use it. That is something that could easily be ignored if,\nsay, someone just expected
duration<\/code> to be in milliseconds. The second doesn’t need the comment. Given how\nstd::chrono::duration<\/code> is defined it doesn’t matter whetherduration<\/code> is given in seconds, milliseconds,\nor whatever. However the function is called it will be translated into the correct units when it is used.\nThat’s not as good as using a comment, it’s better.<\/p>\n\n\n\nUnits of measurement<\/h2>\n\n\n\n
It’s easy to imagine extending this beyond time. There could be types to represent all sorts of quantities that\nwe measure: time, distance, mass, temperature,\nall the scientific units<\/a>.\nThen there are all the ways those can be combined: force, pressure, energy and more.\nThat would be a lot of types to define individually but we don’t have to.\nWe can define base units and then combine them together to create derived units.\nThe details of this are going to be complicated but mp-units<\/a> shows it can be done.\nYou could end up with something like this:<\/p>\n\n\n\n
auto distance = 10 * meters;\n auto time = 5 * seconds;\n auto speed = distance \/ time;\n std::cout << speed << std::endl;\n \/\/ Prints: 2 meters \/ seconds<\/pre><\/div>\n\n\n\nAgain, the advantage here is not only in documentation but also that the units that you use don’t matter any more.\nThe Mars Climate Orbiter<\/a> is a failed Mars mission.\nIt was destroyed because one team used SI units<\/a> and\nanother team used US customary units<\/a>.\nUsing these typed measurements different teams could use different units and they would be converted automatically.<\/p>\n\n\n\n
Success and failure<\/h2>\n\n\n\n
It’s common to have functions that return the indication of success or failure via a boolean.\nIt may be obvious that this is the intent or it may not be.\nIt leads to many comments of the form:<\/p>\n\n\n\n
\/\/ Returns true if successful and false otherwise.<\/pre><\/div>\n\n\n\nSometimes an enumeration is used instead of a boolean to make this more explicit:<\/p>\n\n\n\n
enum Outcome {\n Success,\n Failure\n};<\/pre><\/div>\n\n\n\nIt could be even better to have a fully formed class:<\/p>\n\n\n\n
class Outcome {\n Outcome(bool value);\n \n operator bool() const;\n...\n};\n\nconst Outcome Success(true);\nconst Outcome Failure(false);<\/pre><\/div>\n\n\n\nThis doesn’t need a comment about any return value, is easy to create,\nand can be used directly in, say, an if-statement to control the response to the outcome.<\/p>\n\n\n\n
Error<\/h2>\n\n\n\n
If you want to know more than a simple success or failure then an enumeration or\nexception handling are the typical ways to go. A custom class is another option.\nSomething like this:<\/p>\n\n\n\n
class Error {\n Error(const std::string& message);\n\t\n operator bool() const;\n...\n};\n\nconst Error NoError = Error::GetNoError();\nconst Error FileNotFound("File not found");<\/pre><\/div>\n\n\n\nAgain this doesn’t need to comment the return value and can be used directly in control flow.\nA set of standard errors can be defined alongside the
Error<\/code> class. However, unlike enums, other\nsystems can add their own error values and their is no risk of re-using values.<\/p>\n\n\n\nCount<\/h2>\n\n\n\n
I was working on
ByteArray<\/code> classes recently.\nThis allowed bytes to be easily re-interpreted as immediate types, structs and arrays.\nThe interface was easy for most types but less clear for arrays:<\/p>\n\n\n\nclass ByteArray {\n...\n template <typename Type>\n const Type& Get(uint64_t position);\n \n template <typename Type>\n const std::range<Type>& GetRange(uint64_t position, uint64_t size_in_bytes);\n...\n};<\/pre><\/div>\n\n\n\nGiven that the position was measured in bytes it seemed to make sense that the size should also be\nmeasured in bytes. However it was typically used to get a know number of objects.\nThat meant an extra size conversion every time. This can be made explicit.<\/p>\n\n\n\n
const auto intsByByte = byteArray.GetRange<uint32_t>(0, Count<byte>(40));\n const auto intsByObject = byteArray.GetRange<uint32_t>(0, Count<uint32_t>(10));\n assert(intsByByte == intsByObject);<\/pre><\/div>\n\n\n\nI’m slightly dissatisfied with this as it makes the code seem bulky. However it reduces the chance\nof someone getting the wrong range. Even if someone hasn’t read the documentation they have to use it correctly.\nThis could also be useful in an interface where several things are being counted and they could be confused.<\/p>\n\n\n\n
Quantity<\/h2>\n\n\n\n
You might also want to have finer discrimination of what is being measured.\nA typed variant of a floating-point number or even the units of measurement from earlier could\nknow what it is measuring.<\/p>\n\n\n\n
const Quantity<Oxygen> oxygen(50 * litres);\n const Quantity<Hydrogen> hydrogen(100 * litres);\n const auto water = React(oxygen, hydrogen);\n std::cout << water << std::endl;\n \/\/ Prints: H2 O * 50 litres<\/pre><\/div>\n\n\n\nOn balance<\/h2>\n\n\n\n
That’s just a few possibilities that I threw together quickly, I’m sure there are more out there.\nWhile I didn’t like the “no comment code” in general that doesn’t mean it doesn’t have something to say.\nDon’t dismiss and entire set of ideas just because you don’t agree with a few of them.<\/p>\n","protected":false},"excerpt":{"rendered":"
Last year I watched a YouTube video about “no comment code” which, to me, sounded like a terrible idea. A quick web search shows that not commenting code has it’s proponents. Let’s not get into that right now. While I didn’t agree with the video as a whole I did like one specific idea: Use […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_import_markdown_pro_load_document_selector":0,"_import_markdown_pro_submit_text_textarea":"","footnotes":""},"categories":[1],"tags":[16],"class_list":["post-71","post","type-post","status-publish","format-standard","hentry","category-general","tag-methodologies"],"_links":{"self":[{"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/posts\/71","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/comments?post=71"}],"version-history":[{"count":3,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/posts\/71\/revisions"}],"predecessor-version":[{"id":196,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/posts\/71\/revisions\/196"}],"wp:attachment":[{"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/media?parent=71"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/categories?post=71"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/tags?post=71"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}