9

I am an assistant professor for a course on audio signal processing (for engineers) and I often write snippets of code to try to help the students follow the material. In addition, I get to lecture (1) one session of the course.

I have a lot of code I wrote over the last couple of years for this particular session but I realized my comments on it are not consistent at all and I have not found any sort of standards or guidelines for pedagogically appropriated commenting style.

Should I comment this code like I normally do with any code?

I usually add a header comment explaining which course the code was written for and something about what it is showing. But I also tend to comment the code with some trivialities in order to state somethings that I think would be obvious to developers but not to engineering students.

Improve this question
2
  • 8
    I don't really understand what you're asking us.
    – ff524
    Aug 31, 2015 at 2:37
  • I am looking for some kind of standard/guide and/or advice as to how to comment code that has educational purposes.
    – Andrés Marafioti
    Aug 31, 2015 at 3:55

5 Answers 5

Reset to default
3

This is not a standard, but these are some considerations that have helped me:

If I give code for students I take special care to be consistent (I am not always successful). Students tend to find inconsistencies and think there must be a reason for that and start looking for reasons where none exist.

I also consider the purpose of the snippet: is it an example of best practice or an illustration of how such code works. In the former case I would be less verbose with my comments then in the latter case.

Sometimes it helps to have a list of trivial tricks separate from the example code. Here is an example I have used. This can be an alternative to commenting tricks in your code that are not central to the point you want to make with that example.

Improve this answer
2
  • I love the idea of a list of trivial tricks. I try to explain these sort of things either orally or with comments on the first code they appeared in. That wasn't working for me. When I add a snippet of code to the beginning of the course I have to track down where I commented why I do it like that just to make sure I am consistent with the reasoning.
    – Andrés Marafioti
    Aug 31, 2015 at 12:00
  • Ask your students for feedback on mistaken comments and such.
    – vonbrand
    Sep 1, 2015 at 0:26
7

I think the Linux kernel is a good standard.

In general, don't explain what are you doing, that should be obvious from the code. Do tell why you are doing it. Let me show an example:

data_padded = pad_with_zeroes(data, 2**ceil(log2(len(data))))
fft(data_padded)

Everybody can see that I am padding it with zeroes, and any engineer student should see I am doing it to the next power of two (modulo bugs). But they may not be aware why are you doing it: a comment should point out that a FFT is fastest when the input length is a power of two.

Also, since this is a very technical setting, add the full names of the algorithms, with alternative names if they are common, and at least a reference using the same definition as you are. Tracking down factors of 2 π can be a pain.

Improve this answer
4
  • 2
    +1 let the code speak whenever possible. This is thaught in introductory software engineering courses.
    – user7112
    Sep 1, 2015 at 11:45
  • 2
    This is true advice and not only for educational purposes but for your own sanity. What makes perfect sense now won't in 6 months time when you need to make a feature change.
    – scrappedcola
    Sep 1, 2015 at 14:00
  • Until now this is the best answer. I do tend to make my code as readable as possible. In my work, I keep comments to a minimum and have never received complaints about it. My problem comes when I want to explain that a portion of the code should be an independent function or that you can call only a portion of a vector inside a plotting method. My comments are in the lines of 'Pay attention to the way this function treats its inputs, do you see room for optimization?'
    – Andrés Marafioti
    Sep 1, 2015 at 21:34
  • @AndrésMarafioti, perhaps complement the code (written in your customary style) with external highlights/explanations. That way you can even have different explanations according to audience.
    – vonbrand
    Sep 2, 2015 at 0:15
2

The same way you would comment this if writing it professionally -- unless you really think you're doing something too obscure for the students to follow after you've pointed it out.

Improve this answer
1

Should I comment this code like I normally do with any code?

Apart from the answers on good commenting style, I would consider copyright or license in the header comments. Make it explicit. See https://stackoverflow.com/a/134249/1168342 for the accepted answer that mentions copyright/license (and other perspectives).

My university uses similarity-detection software in programming assignments (MOSS), and also requires students to cite sources of reused information (code). Adding license/copyright info could be useful if students copy your code and re-use it in a project without citing the source.

Since adding a header to every file could be a lot of work, there's a possible solution. Assuming you want it to be open source, putting all your code snippets in a github repository with a chosen license might be a good idea. See https://help.github.com/articles/open-source-licensing/ for details.

Improve this answer
7
  • 3
    This does not answer the question.
    – JeffE
    Aug 31, 2015 at 22:54
  • Is that last edit better @jeffe?
    – Fuhrmanator
    Aug 31, 2015 at 23:49
  • I'm not sure that "the repo license covers all" is legally correct.
    – vonbrand
    Sep 1, 2015 at 0:27
  • @vonbrand I agree lawyers can always argue it. But I added a link to what github says about it.
    – Fuhrmanator
    Sep 1, 2015 at 0:40
  • 2
    Not really, no. OP is asking about pedagogically appropriate commenting style. Your answer is about licensing, which is an entirely orthogonal issue.
    – JeffE
    Sep 1, 2015 at 16:30
1

There is a fundamental conflict in producing code for teaching in terms of comments between providing the high level of detail required for people who are learning and will not understand even the simpler parts of the code, and acting as a role model for how professionals should be commenting their code.

The majority of example and tutorial code I have seen solves this by simply ignoring the second of these aims. I do not think this is necessarily a bad thing, however, if you are more concerned about demonstrating the latter then I would suggest that you comment your code with a more minimal approach and then provide an annotated version of the code with the additional information needed for teaching.

Improve this answer
0

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .