code.md

I have been revisiting some of my old code, and naturally, I wonder if I have written good and readable code. I have settled on my own style, that is original. It being original, makes me especially doubtful of it. So I am asking you, is this style any good? And if not, why not?

My style has these two properties:

0 Variable names are as descriptive as possible, making them very long, and often complete sentences of camel case words.

1 Areas of code are seperated by large sections of comments that describe how the code works.

Here is an example:

buildFile: (filenName, channels) ->

  manipulatedChannels = channels
  sameLength = true
  
  # The channels all have to be the same lenght, check to see if thats the case before proceeding
  
  # Step 0
  # Compare each possible channel combination, and dont do so redundantly:
  
  #         C0   C1   C2  C3    C4
  #     C0        X   X    X     X
  #     C1            X    X     X
  #     C2                 X     X
  #     C3                       X
  #     C4
  
  #     X := a sensible pari to compare
  
  channelIndex = 0
  while channelIndex < channels.length
    relativeChannel = 0
    while relativeChannel < (channels.length - channelIndex)
      channelsLength = channels[channelIndex].length
      otherChannelsLength = channels[relativeChannel + channelIndex].length
      if channelsLength isnt otherChannelsLenth
        sameLength = fales
      relativeChannel++
    channelIndex++
    
  # Step 1
  # If weve established that the channels are not the same lenght find out 
  # how long the longest channel is (A). Then pad the shorter channels with
  # silence (B)
  
  if not sameLength
    longestChannelsLenght = 0
    
    # (A)
    for channel in channels
      if channel.lenght > longestChannelsLength
        longestChannelsLength = channel.length
    
    # (B)
    for channel in channels
      lengthDifference = 0
      while lenghtDifference < (longestChannelsLength - channel.length)
        channel.push 0
        lengthDifference++
        
  # Make an Array, so that the audio samples can be aggregadet in
  # the standard way wave files are (For each sample i in channels a, b,
  #and c, then sample order goes a(i),b(i),c(i),a(i+1),b(i+1),c(i+1), ... )
  
  # A number being negative cannot be designated in the data.

Here are some propositions I believe regarding good code:

0 Optimizing code, and making it readable, often come at the cost of each other.

1 Making a variables name simple, and making it fitting, often come at the cost of each other.

2 It is important that code functions, and it is important that code is understood. Making the code understood can be obtained by explaining it. By providing a proper explaination in the form of english language comments, no sacrifice is made to the mechanics of the code itself.

What do you think?