Writing source code

Because KDevelop understands your projects' source code, it can assist in writing more code. The following outlines some of the ways in which it does that.

Auto-completion

Probably the most useful of all features in writing new code is auto-completion. Consider, for example, the following piece of code:

class Car {
  // ...
  public:
    std::string get_color () const;
};
void foo()
{
  Car my_ride;
  // ...do something with this variable...
  std::string color = my_ride.ge

In the last line, KDevelop will remember that the variable my_ride is of type Car, and will automatically offer to complete the name of the member function ge as get_color. In fact, all you have to do is to keep typing until the auto-completion feature has reduced the number of matches to one, and then hit the Enter key:



Note that you can click on the tool-tip to get more information about the function apart from its return type and whether it is public:



Auto-completion can save you a lot of typing if your project uses long variable and function names; furthermore, it avoids mis-spelling names (and the resulting compiler errors) and it makes it much simpler to remember the exact names of functions; for example, if all of your getters start with get_, then the auto-completion feature will be able to only present you a list of possible getters when you have typed the first four letters, likely reminding you in the process which of the functions is the correct one. Note that for auto-completion to work, neither the declaration of the Car class nor of the my_ride variable need to be in the same file as where you are currently writing code. KDevelop simply has to know that these classes and variables are connected, i.e. the files in which these connections are made need to be part of the project you are currently working on.

Note

KDevelop doesn't always know when to assist you in completing code. If the auto-completion tooltip doesn't automatically open, hit Ctrl+Space to open a list of completions manually. In general, in order for auto-completion to work, KDevelop needs to parse your source files. This happens in the background for all files that are part of the projects of the current session after you start KDevelop, as well as while after you stop typing for a fraction of a second (the delay can be configured).

Note

KDevelop only parses files that it considers source code, as determined by the MIME-type of the file. This type isn't set before the first time a file is saved; consequently, creating a new file and starting to write code in it will not trigger parsing for auto-completion until after it is saved for the first time.

Note

As in the previous note, for auto-completion to work, KDevelop must be able to find declarations in header files. For this, it searches in a number of default paths. If it doesn't automatically find a header file, it will underline the name of a header file in red; in that case, right click on it to tell KDevelop explicitly where to find these files and the information they provide.

Note

Configuring auto-completion is discussed in this section of this manual.

Adding new classes and implementing member functions

KDevelop has an assistant for adding new classes. The procedure is described in Creating a new class. A simple C++ class can be created by choosing the Basic C++ template from the Class category. In the assistant, we can choose some predefined member functions, for example an empty constructor, a copy constructor and a destructor.

After completing the assistant, the new files are created and opened in the editor. The header file already has include guards and the new class has all the member functions we selected. The next two steps would be to document the class and its member functions and to implement them. We will discuss aids for documenting classes and functions below. To implement the special functions already added, simply go to the bus.cpp tab where the skeleton of functions are already provided:



To add new member functions, go back to the bus.h tab and add the name of a function. For example, let us add this:



Note how I have already started with the implementation. However, in many coding styles, the function shouldn't be implemented in the header file but rather in the corresponding .cpp file. To this end, locate the cursor on the name of the function and select CodeMove to source or hit Ctrl+Alt+S. This remove the code between curly braces from the header file (and replaces it by a semicolon as necessary to terminate the function declaration) and moves it into the source file:



Note how I have just started typing and that I meant to imply that the students variable should probably be a member variable of class Bus but that I haven't yet added it. Note also how KDevelop underlines it to make clear that it doesn't know anything about the variable. But this problem can be solved: Clicking on the variable name yields the following tooltip:



(The same can be achieved by right clicking on it and selecting Solve: Declare As.) Let me select 3 - private unsigned int (either by mouse, or by hitting Alt+3) and then see how it comes out in the header file:



It is worth noting that KDevelop extracts the type of the variable to be declared from the expression used to initialize it. For example, if we had written the addition in the following rather dubious way, it would had suggested to declare the variable as type double:



As a final point: The method using CodeMove to source does not always insert the new member function where you may want it. For example, you may want it to be marked as inline and place it at the bottom of the header file. In a case like this, write the declaration and the start writing the definition of the function like this:



KDevelop automatically offers all possible completions of what might come here. Selecting one of the two add_students entries yields the following code that already fills in the complete argument list:



Note

In the example, accepting one of the choices the auto-completion tool offers yields the correct signature but unfortunately deletes the inline marker already written. This has been reported as KDevelop Bug 274245.

Documenting declarations

Good code is well documented, both at the level of the implementation of algorithms within in functions as well as at the level of the interface — i.e., classes, (member and global) functions, and (member or global) variables need to be documented to explain their intent, possible values of arguments, pre- and postconditions, etc. As far as documenting the interface is concerned, doxygen has become the de facto standard for formatting comments that can then be extracted and displayed on searchable webpages.

KDevelop supports this style of comments by providing a short cut to generate the framework of comments that document a class or member function. For example, assume you have already written this code:

class Car {
  public:
    std::string get_color () const;
};

You now want to add documentation to both the class and the member function. To this end, move the cursor onto the first line and select CodeDocument Declaration or hit Alt+Shift+D. KDevelop will respond with the following:



The cursor is already in the grayed out area for you to fill in the short description (after the doxygen keyword @brief) of this class. You can then continue to add documentation to this comment that gives a more detailed overview of what the class does:



While the editor is inside the comment, the comment text is highlighted in green (the highlighting disappears once you move the cursor out of the comment). When you get to the end of a line, hit Enter and KDevelop will automatically start a new line that starts with an asterisk and place the cursor one character indented.

Now let's document the member function, again by putting the cursor on the line of the declaration and selecting CodeDocument Declaration or hitting Alt+Shift+D:



Again, KDevelop automatically generates the skeleton of a comment, including documentation for the function itself, as well as its return type. In the current case, the name of the function is pretty much self-explanatory, but oftentimes function arguments may not be and should be documented individually. To illustrate this, let's consider a slightly more interesting function and the comment KDevelop automatically generates:



Here, the suggested comment already contains all the Doxygen fields for the individual parameters, for example.

Renaming variables, functions and classes

Sometimes, one wants to rename a function, class or variable. For example, let's say we already have this:



We then realize that we're unhappy with the name remove_students and would have rather called it, say, throw_out_students. We could do a search-replace for the name, but this has two drawbacks:

  • The function may be used in more than one file.

  • We really only want to rename this function and not touch functions that may have the same name but are declared in other classes or namespaces.

Both these problems can be solved by moving the cursor on any of the occurrences of the name of the function and selecting CodeRename declaration (or right clicking on the name and selecting Rename Bus::remove_students). This brings up a dialog box where you can enter the new name of the function and where you can also see all the places where the function is actually used:



Code snippets

Most projects have pieces of code that one frequently has to write in source code. Examples are: for compiler writers, a loop over all instructions; for user interface writers, checks that user input is valid and if not to open an error box; in the project of the author of these lines, it would be code of the kind

for (typename Triangulation::active_cell_iterator
       cell = triangulation.begin_active();
     cell != triangulation.end(); ++cell)
  ... do something with the cell ...

Rather than typing this kind of text over and over again (with all the concomitant typos one introduces), the Snippets tool of KDevelop can help here. To this end, open the tool view (see Tools and views if the corresponding button isn't already on the perimeter of your window). Then click on the Add repository button (a slight misnomer — it allows you to create a named collection of snippets for source codes of a particular kind, e.g. C++ sources) and create an empty repository. Then click to add a snippet, to get a dialog like the following:



Note

The name of a snippet may not have spaces or other special characters because it must look like a normal function or variable name (for reasons that will become clear in the next paragraph).

To use a snippet so defined, when you are editing code, you can just type the name of the snippet like you would any other function or variable name. This name will become available for auto-completion — which means that there is no harm in using a long and descriptive name for a snippet such as the one above — and when you accept the suggestion of the auto-completion tooltip (for example by just hitting Enter), the already entered part of the snippets' name will be replaced by the full expansion of the snippet and will be properly indented:



Note that for this to work, the Snippets tool view need not be open or visible: you only ever need the tool view to define new snippets. An alternative, if less convenient, way to expand a snippet is to simply click on it in the respective tool view.

Note

Snippets are much more powerful than just explained. For a full description of what you can do with them, see the detailed documentation of the Snippets tool.