[Kdenlive-devel] Could you PLEASE document your code.

[Simon Eugster]

I wanted to continue working on my audio spectrum scope. So I made use of
void Render::showAudioSignal(const QByteArray);
until I found out that this wasn't delivering the audio signal at all
because I only received two values per frame.

So I searched for the position where this signal was emitted:
void Render::showAudio(Mlt::Frame& frame)
{
    if (!frame.is_valid() || frame.get_int("test_audio") != 0) return;
    mlt_audio_format audio_format = mlt_audio_s16;
    int freq = 0;
    int num_channels = 0;
    int samples = 0;
    int16_t* data = (int16_t*)frame.get_audio(audio_format, freq,
num_channels, samples);
    if (!data)
        return;
    int num_samples = samples > 200 ? 200 : samples;
    QByteArray channels;
    for (int i = 0; i < num_channels; i++) {
        long val = 0;
        for (int s = 0; s < num_samples; s ++) {
            val += abs(data[i+s*num_channels] / 128);
        }
        channels.append(val / num_samples);
    }
    if (samples > 0)
        emit showAudioSignal(channels);
    else
        emit showAudioSignal(QByteArray());
}
After skimming the entire function's code I found out that this only
shows the mean of the (at most) first 200 audio sample points.
Which I doubt is not correct anyway for a volume meter.





So –
. Could you, please, document the code you write.

Some parts look like «if it was hard to write, then it should be hard
to read». This is okay for me if it is your own code which is not made
public. But this is a collaborative Open Source project. It DOES
occasionally happen that others have to take a look at your code,
understand it, use it, fix bugs, extend it. Reading undocumented code
sucks. If you don't know what methods are good for and why, you have
to read everything, look out for possible side effects which might
crash everything, and so on.

Example: Understand this code within 2 minutes:
http://git.gnome.org/browse/gimp/tree/app/base/gimphistogram.c

And it is not unlikely that even _you_ will eventually have to
re-visit your own code after some weeks/months/years. As soon as it
reaches a certain complexity I'm usually very glad when I can just
read some comments to understand the workflow again because I usually
don't remember everything in detail.

By documenting I don't mean:
            // Add the current value, divided by 128
            val += abs(data[i+s*num_channels] / 128);
i.e. writing what a command does. This is overhead and needs to be
maintained in parallel to the code (i.e. when 128 changes to 256 –
What would make sense here is a line explaining why we divide by 128
and not by Pi or by 42.)
But consider this:
    // Calculate the mean of the first 200 samples to approximate the
audio volume
    int num_samples = samples > 200 ? 200 : samples;
    {...}
This explains WHAT a code section does and WHY. I can read one line
and immediately know how a whole code section works.

In my experience, documenting code this way adds to a deeper
understanding of the code for both parties (author and reader), and I
occasionally even found some bugs simply by again having to think
about what the code does (and hereby sparing some time wasting on
debugging).
Lots of clever people have been writing about source code comments.
(One good book I can recommend is «Code Quality» from Spinellis where
he talks about maintainability (which is the core idea for writing
comments; A maintainable piece of software can be
extended/bugfixed/etc much easier) as well.) They all agree that it is
a good thing if done well.
I also see it as an estimation opposite to other programmers.




Regarding the remark about the volume meter not being correct: Our
ears are not linear, and there is also a peak sensitivity around
300-3000 Hz (Human voice). So I guess taking the mean is okay for an
approximation but is not very accurate.


Thanks for reading, happy Sunday.
Simon