File indexing completed on 2024-05-12 04:22:07
0001 // SPDX-FileCopyrightText: 2009, 2013 Jesper K. Pedersen <blackie@kde.org> 0002 // SPDX-FileCopyrightText: 2012 Miika Turkia <miika.turkia@gmail.com> 0003 // SPDX-FileCopyrightText: 2013, 2015-2016, 2018-2020 Johannes Zarl-Zierl <johannes@zarl-zierl.at> 0004 // SPDX-FileCopyrightText: 2021 Johannes Zarl-Zierl <johannes@zarl-zierl.at> 0005 // SPDX-FileCopyrightText: 2022 Johannes Zarl-Zierl <johannes@zarl-zierl.at> 0006 // 0007 // SPDX-License-Identifier: CC-BY-SA-4.0 0008 0009 /** 0010 \page coding-standards Coding Standards 0011 0012 <h2>Compatibility</h2> 0013 0014 Not every distro ships the latest version of Qt. As a rule of thumb, we aim for compatibility with the latest Ubuntu LTS release. 0015 Since invent.kde.org makes it easier to get a continuous integration pipeline for Debian stable, we are currently supporting that as well. 0016 0017 <h3>Why Ubuntu and Debian?</h3> 0018 0019 \li Ubuntu is one of the more popular distros 0020 \li The release life cycle is very regular 0021 \li Debian is easily integrated with our CI pipeline in a way that tracks an older distro. 0022 \li Package information is readily available. See e.g. the information for the 0023 <a href='https://packages.ubuntu.com/search?keywords=cmake' alt='Ubuntu package search'>cmake</a>, 0024 <a href='https://packages.ubuntu.com/search?keywords=extra-cmake-modules' alt='Ubuntu package search'>extra-cmake-modules</a>, 0025 <a href='https://packages.ubuntu.com/libqt5gui' alt='Ubuntu package search'>libqt5gui</a> and 0026 <a href='https://packages.ubuntu.com/libkf5kio-dev' alt='Ubuntu package search'>libkf5kio-dev</a> Ubuntu packages, or 0027 <a href='https://packages.debian.org/search?keywords=cmake' alt='Debian package search'>cmake</a>, 0028 <a href='https://packages.debian.org/search?keywords=extra-cmake-modules' alt='Debian package search'>extra-cmake-modules</a>, 0029 <a href='https://packages.debian.org/search?keywords=libkf5kio-dev' alt='Debian package search'>libkf5kio-dev</a> and 0030 <a href='https://packages.debian.org/search?keywords=libqt5gui' alt='Debian package search'>libqt5gui</> Debian packages. 0031 0032 <h2>Code formatting</h2> 0033 0034 We use clang-format to change our code. Please do use our commit-hooks that are described in `dev/README-dev.txt`. 0035 0036 <h2>General conventions</h2> 0037 0038 Here are a few pointers regarding coding standards in KPhotoAlbum. Please do stick to them, so the 0039 code is easier to get into for new people, and easier to maintain for everyone. 0040 0041 For best results and minimum hassle, please do use clang-format to format your code: 0042 KPhotoAlbum ships with a `.clang-format` file. 0043 0044 \li Basically, we try to stick by the 0045 <a href="https://community.kde.org/Policies/Frameworks_Coding_Style">kdelibs coding style</a>. 0046 \li Instance variables are prefixed with `m_` (not only with `_`). 0047 \li Static instance variables are prefixed with `s_`. 0048 \li Methods that are overridden from a superclass should be marked as such using the C++11 0049 `override` keyword. 0050 \li KPhotoAlbum is warning free zone. Please keep it that way. No warnings during compilations are 0051 accepted. 0052 \li Don't enable debugging statements in production code. 0053 Use categorized logging (QLoggingCategory) with the prefix "kphotoalbum.DIRECTORY" and possibly subcomponents. 0054 You can then enable the code by setting the environment variable QT_LOGGING_RULES="kphotoalbum.*=true". 0055 0056 <h2>Include files and forward declarations</h2> 0057 0058 The order of include statements should always be the following: 0059 0060 \li "config-kpa-xxx.h" includes 0061 \li file-specific header file 0062 \li KPhotoAlbum-includes 0063 \li other includes 0064 0065 To speed up compilation and make things easier to understand, you should be careful about what you 0066 include, and when cleaning up code, please check whether you need all the include files. 0067 0068 In header files you should try hard to see if you really need an include file at all, or whether 0069 you can get by with only a forward declaration. 0070 0071 A forward declaration looks like: 0072 0073 \code 0074 class MyClass; 0075 namespace MyNameSpace { class MyClass; } 0076 \endcode 0077 0078 You can get by with only a forward declaration when all you do is one of these: 0079 0080 \li declare a method that passes a pointer or reference as argument (`doSomething(const MyClass&)`) 0081 \li return an object from a method (`MyClass getClass()`) 0082 \li you only have the class in a container (`QList<MyClass>`) 0083 0084 In contrast you do need the include files when: 0085 0086 \li you declare a method that takes a value argument (`doSomething(MyClass cls)`) 0087 \li you have an instance variable of the given class (`MyClass m_class`). 0088 0089 */ 0090 // vi:expandtab:tabstop=4 shiftwidth=4: