Platinum sponsors
Our extensions follow the following code style guidelines:
on top of that: phpDocumentor documentation
on top of that: TYPO3 Coding Guidelines
on top of that: FLOW3 Coding Guidelines
We then have added a few modifications, additions and clarifications:
Don’t check in commented-out code to SVN. If you absolutely need to do so anyway, you must include a comment (including a reference to a bug) stating when this code can be removed or reactivated.
Use UTF-8 and Unix line endings.
Remove all trailing spaces and trailing tabs.
Lines must not be longer than 80 characters. This also includes comments and documentation comments (also for @param and @return). The only exception are include_once statements (which should be on one line, overriding the 80-character rule) and the declarations of unit tests. Concerning line wrapping, have a look at the line-wrapping guidelines.
File names are allowed to be longer than 31 characters.
Don’t add blank lines after { or before }.
Use a single space after @return, @var, @param, @var, @throws etc., not tabs. (This still needs to be changed in the existing code.)
Use early returns only for guard clauses and only if they greatly improve readability.
Functions that return void don't need to have a return statement.
Use @var for member variables.
@var should always be in multi-line style:/** * @var type description */
Functions that return void don't need to have a @return.
@param should include the type, the parameter name and a description.
@param array $types the allowed types
If the description doesn’t fit on the first line, start on a new line and indent the description to align with the type:
@paramarray $types
the types that are allowed, must always include at least one non-green type and must not
contain any aliens with smelly feet
Sentences in comments (including @param and @return) should either be
incomplete sentences that start lowercase and don’t have a full stop at the end, or
complete sentences that have a capital letter at the start and a full stop at the end.
Comments should be written in the third person (or in the first person in some cases).
Put the documentation comment for a class directly above the class statement. Include statements should be above the class comment so that PhpDocumentor doesn’t complain.
Use @throws for documenting exceptions that need to be caught by the caller (checked exceptions).
Don’t use @throws when the exception does not need to be caught by the caller (unchecked exceptions). Examples of this are exceptions for a database failure or exceptions that are thrown only when the contract is violated, , e.g. when a UID for which the @param states that it must be >= 0 is -42.
Use strict camelCase for function and variable names. Good: createIndex, readIsoImage. Bad: create_index, readISOImage.
Class names need to contain the path so that the autoloader can work: EXT:foo/Model/class.tx_foo_Model_Chicken.php
Private and protected function and variable names must not begin with an underscore.
Testing classes:
Testing classes that are basically a fully-fledged subclass of another class should be prefixed “testing”. Example: A testing subclass of foo should be named testingFoo.
Testing classes that fake some of their behavior to reduce dependencies or API calls should be prefixed with “fake”. Example: Such a testing subclass of foo should be named fakeFoo.
Test case classes should be suffixed with _testcase. Example: A testcase for the seminar class should be named seminar_testcase (if there is only one testcase for that class).
Test functions should be named test_<function name>_<parameters or preconditions>_<expected result or behavior> (with or without the underscores). Example: test_GetAsString_WithInexistentKey_ReturnsEmptyString. Instead of the “test” prefix, the @test annotation may be used.
The development process looks roughly like the process on Mozilla.org and aims at creating high-quality code and facilitating learning from other coders.
Make sure to always use the latest code and documentation from SVN.
Look in the bug tracker if your specific bug or feature request already has been reported. If this is not the case, enter a new bug report/feature request.
Set yourself as the bug's assignee to show you'd like to work on this bug. At this point, the bug status still is NEW.
Assign the bug yourself when you've actually started to work on this bug. This will change the bug's status to ASSIGNED.
Use a test-first approach: When you add a new function or change a function, first write some unit tests that fail as long as the bug is not fixed and that pass when the bug is fixed.
Write the necessary code and test it locally (in addition to the unit tests). Make sure it works and doesn't generate any warnings or errors.
Create a patch. Make sure to read it yourself first. Then attach it to the bug report. Check “patch”, set “review” to “?” and select “Realty Manager QA” in the drop-down list next to the question mark.
The reviewer might give you a review- and list the things that need to be changed. In that case, go back to the previous step and create a new patch.
Or the reviewer might grant you the review, giving you a review+ (possibly listing some things that need to be changed bug that don't require a new review).
If you have the review+, you can update and commit to SVN. Never check in code that has not been reviewed yet! In the check-in comment, write the number of the bug report, what the patch changes and who has reviewed your patch. It is also possible that the reviewer checks the code in.Example: [Bug 1840] Create an extension icon, r/a=Oliver
Resolve the bug report as FIXED.
Notice: To commit files to the SVN, you need a TYPO3 forge account to get write access (please e-mail your user name to Oliver so he can arrange things). If other members of the development team will check your patches in, you don't need an SourceForge.net account.
Please don't change the Manual in SVN (as SVN doesn't allow merging changes in binary files) unless you have explicitly been allowed to do so. Currently, locking files in SVN doesn’t work.
Generally, regressions should be avoided by using unit tests. As some parts of the code are not covered by unit tests (or some cases are not covered yet), regressions might be undetected by the existing unit test. Those regressions than need to be fixed and covered by unit tests. We have agreed on the following strategy for this:
If there have not been any checkins after the checkin that has caused the regressions, we will directly revert the checkin. We then need a fixed version of the patch (including unit tests for the regression). Otherwise:
If a developer can fix the problem within 48 hours (including unit tests for the regression), we will do that. Otherwise:
If we can reverse-apply the patch that has caused the problem within 48 hours, we will do that. We then need a fixed patch. Otherwise:
If all else fails, we will just do our best to fix the problem as fast as possible.
