From WhyNotWiki

Coding conventions  edit   (Category  edit)

Contents 1 Why they are good 1.1 Maintainability 2 2.1 Abbreviations 2.2 Documenting the cases in an if block 3 HTML code 4 C code 5 PHP code 5.1 Placement of {}

[edit] Why they are good

[edit] Maintainability

http://wrath.rubyonrails.org/pipermail/rails-spinoffs/2006-February/002653.html

> I change the indentation in my stuff to tabs (which in all my experience
> have worked across editors), and I also change the bracket styles from
> 
> function() {
> }
> 
> To...
> 
> function()
> {
> }

And in the process have created for yourself a maintenance nightmare if 
you ever intend to upgrade the components that you made "preference 
changes" to.

(There are, actually a few outcomes of upgrading a public component 
after you've made changes to it.  You can replace the component 
outright, at which point, your changes get lost, so why make the changes 
in the first place?  You can attempt to merge the changes, but you can't 
do it using the utilities available (such as diff and patch), which is a 
maintenance problem because it's manual and error prone.  You can choose 
not to upgrade, at which point, you're losing out on the useful 
functionality that others are providing through the proper means.)

In any case, you made that decision for yourself; don't force it on 
others if you release changes to a public component that you think 
others would find useful.

> ...Those are such matters of preference I think there is no point
> bringing that up in reply to someone's functional contributions. That
> was my real point, just sticking up for Sammi in those matters of
> preference.

I commented on this code with an eye towards inclusion.  It was a 
/technical/ review of the bits that I cared about (prototype).  That 
means honoring the coding style of the existing code base and following 
their conventions.  Releasing code that changes "public" components 
(prototype / scriptaculous) without the intention of merging those 
changes back into the public component is doing everyone who adopts 
those changes a disservice.  Now, you could argue that the people who 
adopt said changes are taking this burden upon themselves, but I would 
in turn argue that having useful changes merged back into the public 
component is more efficient for everyone.

Yes, it's a cool new feature, but it's also a maintenance problem.

[Rails-spinoffs Sortable Tree Addition [PATCH]] (http://wrath.rubyonrails.org/pipermail/rails-spinoffs/2006-February/002673.html). Retrieved on 2007-05-11 11:18.

Everyone has their own opinion on coding standards. I'm of the opinion that coding standards are bunk and any programmer worth his paycheck can read code no matter how it is indented or where the [...] brackets are placed. If the owner of a project chooses to enforce certain ones, though, then contributors to the project should abide by them. Otherwise, do whatever you want with your own stuff.

[edit]

[edit] Abbreviations

Should you call your variable return_value, return_val, or ret_val? When is it appropriate to abbreviate?

[edit] Documenting the cases in an if block

Should the comments go before the case, at the beginning of the case, or on the same line as the case?

Example:

Before the case:

        # Use the parent's value if self's value is blank
        if self.send(non_virtual_method_name).blank? and self.parent != nil
          return self.parent.send("virtual_" + non_virtual_method_name)
        # Use self's value if it is present
        else
          return self.send(non_virtual_method_name)
        end

At the beginning of the case:

        if self.send(non_virtual_method_name).blank? and self.parent != nil
          # Use the parent's value if self's value is blank
          return self.parent.send("virtual_" + non_virtual_method_name)
        else
          # Use self's value if it is present
          return self.send(non_virtual_method_name)
        end

On the same line as the case (can make the lines very long, so I don't like it):

        if self.send(non_virtual_method_name).blank? and self.parent != nil # Use the parent's value if self's value is blank
          return self.parent.send("virtual_" + non_virtual_method_name)
        else # Use self's value if it is present
          return self.send(non_virtual_method_name)
        end

[edit] HTML code

http://www.ghostscript.com/doc/current/Htmstyle.htm

[edit] C code

http://www.ghostscript.com/doc/current/C-style.htm

[edit] PHP code

(Parent: Source code: C-like languages)

[edit] Placement of {}

try {
  do_something();
}
catch  (Exception $exception) {
  // handle it
}

not:
try {
  do_something();
} catch  (Exception $exception) {
  // handle it
}


Similarly:
if (...) {
}
else {
}

not:
if (...) {
} else {
}