Basic Programming Skills for Everyone

You are expected to possess various trivial programming skills and use them for all your hand-ins. You find a list here.

Comments

Comments in code have no influence on the actual running of the program. It can make the understanding of the code easier (or harder) in several ways, both for the author of the program, but also for a causal reader, who must understand/maintain the code. Comments must not be underestimated in their importance for making the code easier to understand. Both the reading and writing of the comments enhance this understanding. Thus it is a good idea to write the comment first as that focuses your mind on what you have to do.

Placement

As a surface requirement, the placement of the comment is critical. Comments can disturb the reading of the code by making it difficult to distinguish between code and comments, usually by being placed in non-systematic ways. Good placement of comments enhance readability of the code, simply by "looking nice" (actual reading not required), and by separating different elements/parts of the program from each other.

Content

Looking at the content of the comments, it must describe what is going on in this part of the code. Irrelevant, misleading or directly wrong content is harmful for understanding and hence maintenance. The content must be easy to read and understand. The content can be a headline for trivial code, or more throughout explanation for intricate parts.

Amount

The amount of comments is also of importance. Filling the code with comments about every little detail is not beneficial, but neither are too few comments, so the reader has to guess at what is going on. What describes the amount of comments best? :

Modularization

Spacing

While comments in the code can provide some spacing, then judiciously placed empty lines can enhance the reading of a program, by separating parts from each other. Making code is stringing a lot of ideas together in a step-wise fashion. Empty lines can separate these steps - making it clear when you are doing something new - the next step.

Modularization

Modularization of the code hangs together with the use of spacing (empty lines and comments). When separating the parts/steps of the code, then the separation should be true, i.e. a line (or more) of code that conceptually belongs to one part should not be in another part. This can be (and often is) as simple as placing the spacing the right place, or more complex considerations about what code belongs to what part. If a piece of code is consisting of a mix of two (or more) steps/parts, it is not well modularized. At some point modularization also becomes a question about making good functions with well-defined specific purposes.

Naming

Any program will contain variables and other objects of generic nature. By naming the variables/objects well, the readability of the code will be greatly enhanced and conversely by using nonsensical, misleading or directly wrong names, the reader will be confused - that includes you. Short practical example: Imagine reading a book with all o's replaced with x. Now replace all the e's with b, too - and so forth.

Any name must reflect the nature and/or purpose of the variable/object. It is well worth considering a name for a while, as you will use it several times in your code and the way you think about the name will influence the way you use the variable and the meaning you attach to it. Being systematic and consistent in naming is beneficial. It can be achieved in several ways (showing a few); using a specific naming convention - like camelCase, always use i in trivial for-loops, always end a variable name with 'Pos', if it denotes a position somewhere. Too long a name is annoying to use/read, too short or abbreviated name can become nonsensical.

Variable use

Code can easily get confusing by using more variables than truly necessary. This is typically seen when you do a lot of copying content from one variable to another, or other situations where the value of one variable carries a subset of the same meaning/value as another. It is bad code and a sign of lack of overview.

Another confusing issue is when a variable is used for different purposes different places in the program. A variable should only represent one thing/concept.

A variable should never change data type. If it does, then you did not realize from the beginning what you want to use it for - what it represents.

In other situations the given problem (the data) is represented in an inappropriate data type. This happens most frequently with the collection types, i.e. a dictionary is used where a list would be better or vice versa.

Input control, error handling

A lot of the code in a program is handling the input to the program - from keyboard or file. Many trivial errors come from accepting inappropriate input. It could be the wrong type of input (text instead of number), a number is not within the expected/accepted range or expecting DNA but getting protein sequence. As far as possible trivial control of input should be implemented and "nice" error handling enforced, i.e. informing the user of the problem, so it can be corrected. Check the box that describes the input control best:

Error scenarios

Even when the program is fed input, which at least on the surface is correct, situations can occur where the program breaks down or produces wrong output. This is often due to extreme cases where the programmer does not care or cannot imagine the situation occurring. None the less, it is possible find and handle such errors by observing inconsistencies in the result. A good way of finding such error scenarios is to see if you can imagine some input, which will cause the program to break.

Issues with the code

Simple structural flaws in code

This covers directly observable minor flaws in the structure of the code.

• If-statement; No empty statement, i.e. no "else: pass", or "if x==0": pass else: z=1". No repeat of a statement in both true/false cases - usually an increment of the same variable.
• For-loops; Don't change the value of the loop variable inside the loop.
• Sometimes a while is used instead of an if and the code will work with both due to the way the code work - the while is effectively only iterated once => change to if.
• Conditional logic; or is used instead of and, or vice versa. This happens because when we speak, we often mix up and and or when we argue logic. This is translated to the code you write.

Code clarity

The simple structural flaws above will definitely reduce clarity of the code, and so will "bad" comments and variable names, wrong spacing and modularization. Disregarding these which have been covered, there are still some elements of clarity not yet discussed.

• All loops - especially while loops - should be initialized properly. Basically this means variables should be set to contain the proper values so the loop can progress correctly. This is done just before the loop and can be thought of as part of the modularization. It can be that no initialization is required or in more complex situations it may not be possible.
• If possible with nested loops - do not reset a key variable after the loop, but initialize instead before the

loop. Functionally it is the same result, but initialization is easier to read. Declare/initialize your variables near the code where they are used, when possible. This can be considered an aspect of modularization.

• Write explicit code. In Python this is most easily achieved by not making too long and complex lines. Break them up in simpler lines.
• Write direct code, i.e. avoid code bloat. While code bloat is hard to quantify, then it can be easy to see. This happens when people write a lot of code, which could have been written much simpler and much more directly towards the goal. When you see code bloat, it can be hard to point the finger to any specific part of the code, which is wrong. The code might not be wrong at all, it is just bloated.

Algorithm clarity

This is the highest abstraction level covered. It is a metric for how easy it is to follow the "purpose" of the code and the "ways" or "mechanisms" it uses to achieve this purpose. It could also be described as how easy is it is to follow the thoughts and logic of the programmer. This can be slightly subjective - be careful about that.