Loading ...
Sorry, an error occurred while loading the content.

formatting conventions

Expand Messages
  • Seth Dillingham
    frntierkernel.org lists a bunch of formatting conventions for writing kernel code. I find many of the conventions used in the source to be quite maddening,
    Message 1 of 7 , May 13 3:24 PM
    • 0 Attachment
      frntierkernel.org lists a bunch of "formatting conventions" for writing
      kernel code.

      I find many of the conventions used in the source to be quite maddening,
      like alllowercasenounderscoresinfunctionnames.

      You'll never hear me suggest that we go back and change all the old
      stuff, but I really, really, really hate the idea of being stuck with
      that formatting in everything new we write.

      Andre recently added "The following guidelines for formatting the kernel
      code were not set arbitrarily. Most of the kernel code already followed
      these guidelines when UserLand released the code as open source."
      Perhaps this was his quiet way of pointing out the error of my ways, as
      many of my recently added functions don't use the
      indeciperhablefunctionname style, or perhaps it's just coincidence.

      We're trying to make the kernel better, to move beyond the way things
      were done in the past. Couldn't the coding style evolve along with the
      functionality?

      Of course, I'll live with it if I must. But, must I?

      Seth
    • Andre Radke
      ... Here s the link: http://frontierkernel.org/developers/hacking Due to lack of time, I wrote down those formatting conventions off the top of my head in a
      Message 2 of 7 , May 13 4:41 PM
      • 0 Attachment
        Seth Dillingham wrote:
        >frntierkernel.org lists a bunch of "formatting conventions" for writing
        >kernel code.

        Here's the link:

        http://frontierkernel.org/developers/hacking

        Due to lack of time, I wrote down those formatting conventions off
        the top of my head in a couple of minutes without actually referring
        to the source code. Therefore, I expect them to be incomplete.

        >We're trying to make the kernel better, to move beyond the way things
        >were done in the past. Couldn't the coding style evolve along with the
        >functionality?

        While reading the commit notifications, I noticed that the coding
        style is already evolving, but not in a coordinated fashion.

        While you may have chosen unconventional function names, I noticed
        other committers breaking up function headers into one line each per
        parameter or reformatting comments to list most recent changes first.
        I haven't called anybody out for not conforming to the conventions
        because they weren't written down anywhere and because we had not
        discussed this previously.

        Personally, I'm open to evolving the formatting conventions, but I
        would prefer that we all stick to the same set of conventions.

        -Andre



        --
        Andre Radke + http://spicynoodles.net/
      • creecode@gmail.com
        Hello all, ... Here is one formatting convention I d like to see followed. Comment changes to a function at the top of the function. Comments should be dated
        Message 3 of 7 , May 13 5:44 PM
        • 0 Attachment
          Hello all,

          >Personally, I'm open to evolving the formatting conventions, but I
          >would prefer that we all stick to the same set of conventions.

          Here is one formatting convention I'd like to see followed. Comment
          changes to a function at the top of the function. Comments should be
          dated and signed by author. Comments should be in reserve
          chronological order. I find it easier to find a function by name and
          then be able to see recent changes right there at the top of the
          function without having to scroll down to the bottom of the comments
          section. This is similar to blogging or how some folks have been
          commenting scripts more recently.

          --
          Toodle-looooooo........
          creecode

          website hosting: < http://www.editHere.com/ >, email: < creecode@... >
        • creecode@gmail.com
          ... Guilty! :-) I m pretty sure there was precedent for this in the kernel before I did it myself. One reason I have done it is because I find it very
          Message 4 of 7 , May 13 6:05 PM
          • 0 Attachment
            >I noticed
            >other committers breaking up function headers into one line each per
            >parameter

            Guilty! :-) I'm pretty sure there was precedent for this in the
            kernel before I did it myself. One reason I have done it is because
            I find it very difficult to follow functions that have many
            parameters and everything is lowercase. Now if I could get some
            innerCase going I might not have felt the need to split them across
            lines. :-)

            What is the convention for when an opening function line crosses the
            80 character limit? Wrap before the 80 char limit then indent?

            >or reformatting comments to list most recent changes first.

            Guilty! :-)

            I do agree that we should all try to follow established conventions
            and also evolve in a sensible fashion.

            --
            Toodle-looooooo........
            creecode

            website hosting: < http://www.editHere.com/ >, email: < creecode@... >
          • Andre Radke
            ... Actually, I thought Karsten had started this, but it doesn t really matter who did. I m sure there is precedence for deviating from the formatting
            Message 5 of 7 , May 14 3:52 AM
            • 0 Attachment
              creecode@... wrote:
              > >I noticed
              >>other committers breaking up function headers into one line each per
              >>parameter
              >
              >Guilty! :-) I'm pretty sure there was precedent for this in the
              >kernel before I did it myself.

              Actually, I thought Karsten had started this, but it doesn't really
              matter who did.

              I'm sure there is precedence for deviating from the formatting
              conventions in various ways in the pre-open-source code base, but
              that shouldn't justify further deviations. I'm guilty of following my
              own preferences as well, see function names and comment formatting in
              OpenTransportNetEvents.c.

              Starting out from the formatting guidelines I wrote up on
              frontierkernel.org, I'm definitely open to allowing the use of either
              innerCase symbol names or underscores in symbol names as that might
              actually improve readability.

              As for comments at the top of functions, I think we need to do a
              better job of first explaining what the function does, what its
              parameters mean, and what its return value signifies. The comments
              should also document who is responsible for freeing heap-allocated
              parameters (caller, function, or temp stack) and whether the function
              sets up a script error message when it encounters an error. This
              description should ideally be kept up-to-date when changes are made.

              The second part of the comment are the change notes. If we did a
              better job at keeping the function description up-to-date, a
              most-recent first order would be more natural, but it's not such a
              large difference that I would be inclined to switch from most-recent
              last.

              >What is the convention for when an opening function line crosses the
              >80 character limit? Wrap before the 80 char limit then indent?

              Yes, although I'm sure the 80 char limit isn't being followed exactly either.

              -Andre




              --
              Andre Radke + http://spicynoodles.net/
            • Steve Kirks
              ... As an amateur hacker trying to learn the kernel, the items above are crucial. If the comments were in place at the top of a function, I could more easily
              Message 6 of 7 , May 14 7:01 AM
              • 0 Attachment
                On May 14, 2006, at 5:52 AM, Andre Radke wrote:

                > Starting out from the formatting guidelines I wrote up on
                > frontierkernel.org, I'm definitely open to allowing the use of either
                > innerCase symbol names or underscores in symbol names as that might
                > actually improve readability.
                >
                > As for comments at the top of functions, I think we need to do a
                > better job of first explaining what the function does, what its
                > parameters mean, and what its return value signifies. The comments
                > should also document who is responsible for freeing heap-allocated
                > parameters (caller, function, or temp stack) and whether the function
                > sets up a script error message when it encounters an error. This
                > description should ideally be kept up-to-date when changes are made.
                >
                > The second part of the comment are the change notes. If we did a
                > better job at keeping the function description up-to-date, a
                > most-recent first order would be more natural, but it's not such a
                > large difference that I would be inclined to switch from most-recent
                > last.

                As an amateur hacker trying to learn the kernel, the items above are
                crucial. If the comments were in place at the top of a function, I
                could more easily determine the logical flow of the kernel's action
                while in the debugger. In other words, I could more easily see what
                it was trying to accomplish (within the kernel) while executing the
                user's request.

                Steve Kirks
                http://houseofwarwick.com/
                steve.kirks@...
              • Karsten Wolf
                Hello Seth, I knew we agree on more ;-) ... and macros looking like functions (stringbaseaddress()) and lots of (important) globals looking like locals... it s
                Message 7 of 7 , May 14 1:39 PM
                • 0 Attachment
                  Hello Seth,

                  I knew we agree on more ;-)

                  > I find many of the conventions used in the source to be quite maddening,
                  > like alllowercasenounderscoresinfunctionnames.
                  and macros looking like functions (stringbaseaddress()) and lots of (important) globals looking like locals... it's a long list. For beginners it's hard.

                  > You'll never hear me suggest that we go back and change all the old
                  > stuff, but I really, really, really hate the idea of being stuck with
                  > that formatting in everything new we write.
                  I couldn't persuade myself to follow it. OTOH different styles make the sources even uglier.

                  ...
                  > We're trying to make the kernel better, to move beyond the way things
                  > were done in the past. Couldn't the coding style evolve along with the
                  > functionality?
                  >
                  > Of course, I'll live with it if I must. But, must I?
                  That's the hardest part. Ususally I follow the rule to take the style already there...

                  -karsten
                Your message has been successfully submitted and would be delivered to recipients shortly.