platform-core-home/documents/coding_conventions.html
Parent Directory
| 
Revision Log
Revision 1.4 - (view) (download) (as text)
| 1 : | dj | 1.1 | |
| 2 : | <h1 align="center">Eclipse Platform/Core Coding Conventions</h1> | ||
| 3 : | <p align="left">Here are some of the Coding Conventions that we use as a team. | ||
| 4 : | Common code makes it easier for everyone to read and understand.</p> | ||
| 5 : | <h3>Code Formatter:</h3> | ||
| 6 : | <ul> | ||
| 7 : | <li>set line length to be something large (like 800)</li> | ||
| 8 : | dj | 1.2 | <li>turn off formatting for comments</li> |
| 9 : | dj | 1.4 | <li> use the core formatting settings found <a href="core_formatting.xml">here</a></li> |
| 10 : | dj | 1.1 | </ul> |
| 11 : | <h3>Organize imports:</h3> | ||
| 12 : | <ul> | ||
| 13 : | <li> number of imports needed for *: 3</li> | ||
| 14 : | <li> remove all entries in list so we don't use the grouping feature</li> | ||
| 15 : | <li> its all about space...extra blank lines make it hard to read code when | ||
| 16 : | you have a small editor window</li> | ||
| 17 : | </ul> | ||
| 18 : | <h3>Copyright:</h3> | ||
| 19 : | <ul> | ||
| 20 : | <li> make sure the code has the correct copyright.</li> | ||
| 21 : | <li>if the code was written in 2003, don't have 2000,2003 in the copyright</li> | ||
| 22 : | <li>the copyright can be found on the <a href="http://www.eclipse.org/eclipse/eclipse-charter.html%20">Eclipse | ||
| 23 : | Project Charter</a> page.</li> | ||
| 24 : | </ul> | ||
| 25 : | <h3>Code Comments:</h3> | ||
| 26 : | <ul> | ||
| 27 : | <li> comments are a good thing.</li> | ||
| 28 : | <li> comment all "unobvious" things (e.g. don't comment setters/getters)</li> | ||
| 29 : | </ul> | ||
| 30 : | johna | 1.3 | <h3>The art of naming</h3> |
| 31 : | <ul> | ||
| 32 : | <li>Chose class/method/field names that describe the purpose of the entire method/class</li> | ||
| 33 : | <li>Don't use word fragments (getProjectValue is better than getProjVal)</li> | ||
| 34 : | <li>Don't use generic variable names like "temp" or "index" | ||
| 35 : | (Exception: really short methods where usage is very straight-forward. Ok to use i,j, | ||
| 36 : | it for loop indexes)</li> | ||
| 37 : | <li>Don't use get/set prefix unless the method really is just an accessor. If the | ||
| 38 : | method does real work, it's not an accessor. (Note: we don't always follow | ||
| 39 : | this rigorously, but we try).</li> | ||
| 40 : | </ul> | ||
| 41 : | |||
| 42 : | dj | 1.1 | <h3>General: (use the tool!)</h3> |
| 43 : | <ul> | ||
| 44 : | <li>Turn on all the compiler prefs including unused temps, synthetic accessor | ||
| 45 : | methods, unused imports, unused parameters, non-NLS'd strings, etc etc</li> | ||
| 46 : | dj | 1.4 | <li>Turn on compiler warnings for javadoc<br> |
| 47 : | Javadoc -> Process Javadoc comments<br> | ||
| 48 : | - Malformed Javadoc comments -> warning <br> | ||
| 49 : | - Report Errors in tags -> true </li> | ||
| 50 : | dj | 1.1 | <li> NLS your strings. Look at the Policy class.</li> |
| 51 : | <li> Compiler tasks. We have 3 that we use as a team (TODO, FIXME, XXX) Do not | ||
| 52 : | add your own as this is unecessary and requires everyone on the team to change | ||
| 53 : | their compiler settings in order to see these tasks.</li> | ||
| 54 : | dj | 1.4 | <li>Sort the methods within a class alphabetically (use the sort members action).</li> |
| 55 : | dj | 1.1 | <li> All classes MUST have a copyright notice.</li> |
| 56 : | <li> data type size initialization -> use meaningful values if possible, | ||
| 57 : | not things like: new HashSet(65)</li> | ||
| 58 : | <li> Use interfaces when declaring variable types and in method signatures unless | ||
| 59 : | it is necessary to use implementing class</li> | ||
| 60 : | <li> use accessor methods, don't access variables on other classes directly</li> | ||
| 61 : | <li> in general, we use the "true" case of an "if" clause | ||
| 62 : | at the beginning. we also use it to exit a method early. If the whole method | ||
| 63 : | is inside an "if (!foo) {}" then just say "if (foo) return".</li> | ||
| 64 : | <li> ignored exceptions must have a comment saying that they are being ignored | ||
| 65 : | on purpose (compiler warning)</li> | ||
| 66 : | <li> the lines where we create new CoreExceptions and throw them can become | ||
| 67 : | quite long. We usually declare the String message on the line previous to | ||
| 68 : | make it easier to read.</li> | ||
| 69 : | <li> check for null if null could be returned (table look-ups, etc)</li> | ||
| 70 : | <li> should use IPath for path logic rather than Strings and concatination</li> | ||
| 71 : | <li> IPaths are your friend. Replace "new File(location.toOSString())" | ||
| 72 : | with location.toFile();</li> | ||
| 73 : | <li> Don't catch Exception unless you have to. Try to catch specific exceptions.</li> | ||
| 74 : | <li> Don't wrap the whole method in a try {} catch {} block. This makes it hard | ||
| 75 : | to generate specific error messages</li> | ||
| 76 : | <li> if you have nested readers/streams you should only have to call #close() | ||
| 77 : | on the outside one and all wrapped streams should be closed automatically | ||
| 78 : | (note: you may have to call #flush() first)</li> | ||
| 79 : | <li> Ensure all file I/O is buffered.</li> | ||
| 80 : | <li> When sharing code with others, ensure that all the code released to the | ||
| 81 : | repository at least compiles. </li> | ||
| 82 : | <li> Policy.bind() has multiple methods, one of which accepts a single string | ||
| 83 : | as an arg so you don't have to call Policy.bind("message.key", new | ||
| 84 : | String[] { "text" });</li> | ||
| 85 : | </ul> | ||
| 86 : | <h3>NLS'ing your code: messages.properties</h3> | ||
| 87 : | <ul> | ||
| 88 : | <li> all sentences which are displayed to the user must end with a period</li> | ||
| 89 : | <li> include parameters if possible</li> | ||
| 90 : | <li> remove unused messages</li> | ||
| 91 : | <li> make sure if the message accepts a parameter then you pass one in</li> | ||
| 92 : | </ul> | ||
| 93 : | <p> </p> |
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |