KDevelop4/Manual/Arbejdet med kildekode
Arbejdet med kildekode
Ved siden af fejlsøgning er skrivning og læsning af kildekode det, som du vil bruge mest tid med, når du udvikler software. Til dette formål giver KDevelop dig mange forskelige måder at udforske kildekoden og effektivisere skrivning af den. Som det vises i detaljer i de følgende afsnit, så er KDevelop ikke blot en kodeeditor — den er et system til at håndtere kildekode, som giver dig forskellige visninger af information, som findes i de filer, som tilsammen udgør kildekoden i din session.
Værktøjer og visninger
Til arbejdet med projekter har KDevelop begrebet værktøjer. Et værktøj giver dig en særlig visning af kildekoden eller en handling, som det kan udføre. Værktøjer repræsenteres af knapper, som findes rundt omkring i vinduets kant (med lodret tekst langs venstre og højre kant eller vandret langs bunden). Hvis du klikker på dem, så udvides de til et undervindue — en visning — indenfor hovedvinduet. Hvis du klikker på værktøjsknappen en gang til, så forsvinder visningen igen.
Note
Billedet ovenfor viser et eksempel på værktøjer placeret i den venstre og højre kant. I billeder er værktøjet åbent til venstre og værktøjet til højre sammen med en editor til en kildefil i midten. For det meste vil du nok kun have editoren åben og måske værktøjet eller til venstre. Andre værktøjer vil sikkert kun være åbne midlertidigt mens du bruger dem, sådan at der bliver mere plads til editoren.
Når du kører KDevelop første gang, så skulle du allerede have værktøjsknappen . Klik på den: det vil åbne et undervindue, som forneden viser de projekter, som du har føjet til sessionen og en visning af mapperne i dit projekt for oven.
Der er mange andre værktøjer, som du kan bruge i KDevelop, men deres knapper er ikke alle til stede i vindueskanten fra begyndelsen. For at føje flere til vælger du menuen . Her er nogle, som du sikkert vil få glæde af:
- Klasser: En fuldstændig liste af alle klasser, som bliver defineret i en af din sessions projekter med alle deres medlemsfunktioner og -variable. Klik på et medlem for at åbne kildeeditorens vindue med markøren på det sted, hvor det emne, du klikkede på er defineret.
- Dokumenter: Viser de filer, som du for nylig har arbejdet med ordnet efter type (fx kildefil, patchfil eller rent tekstdokument).
- Kodebrowser: Dette værktøj viser ting, der er relaterede til det, som du aktuelt arbejder med afhængigt af, hvor markøren er placeret. Hvis den fx er på en
#includelinje, så vises information om den fil der bliver inkluderet, så som hvilke klasser, der erklæres i filen; hvis du er på en tom linje på filniveau, så vises de klasser og funktioner, som erklæres eller defineres i den aktuelle fil (alle vises som links: klikker du på dem, så bringes du til det sted i filen, hvor erklæringen eller definitionen er); hvis du er i en funktionsdefinition, så vises der, hvor funktionen erklæres og hvor den bruges.
- Filsystem: Giver dig en trævisning af filsystemet.
- Dokumentation: Lader dig søge efter man-sider og andre hjælpedokumenter.
- Snippets: This provides sequences of text that one uses over an over and doesn't want to write every time. For example, in the project from which the picture above was created, there is a frequent need to write code like
for (typename Triangulation<dim>::active_cell_iterator cell = triangulation.begin_active(); cell != triangulation.end(); ++cell)
This is an awkward expression but it will look almost exactly like this everytime you need such a loop — which would make it a good candidate for a snippet.
- Konsole: Opens a command line window inside KDevelop's main window, for the occasional command you may want to enter (e.g. to run
./configure).
En fuldstændig liste med værktøjer og visninger findes her.
For mange programmører er det vigtigst at have god plads i lodret retning. For at opnå dette kan du arrangere dine værktøjsvisninger i venstre og højre vindueskant. For at flytte et værktøj højreklikker du på dets knap og vælger en ny position til det.
Udforsk kildekoden
Lokal information
KDevelop forstår kildekode og er derfor virkelig god til at at give dig information om variable eller funktioner, som kan optræde i dit program. Her er for eksempel et øjebliksbillede af arbejdet med et stump kode, hvor musen svæver over symbolet cell i linje 1316 (hvis du foretrækker at bruge tastaturet, så kan du opnå det samme ved at holde Alt-tasten nede et stykke tid):
KDevelop viser dig et værktøjstip, som inkluderer variablens type (her DoFHandler<dim&rt;active_cell_iterator), hvor denne variabel er erklæret (hvad den er indeholdt i — her den omgivende funktion get_maximal_velocity, eftersom det er en lokal variabel, ikke en funktion, klasse eller navnerum) og hvor den er erklæret (i linje 1314, blot nogle få linjer oppe i koden).
I den aktuelle sammenhæng har symbolet, som musen svæver over ingen tilknyttet dokumentation. Hvis musen havde svævet over symbolet get_this_mpi_process i linje 1318 i dette eksempel, så ville det have set sådan ud:
Her har KDevelop henvist til erklæringen i en anden fil (utilities.h, som endda hører til et andet projekt i den samme session) og vist den doxygen-agtige kommentar, som er knyttet til erklæringen der.
Hvad der gør disse værktøjstips endnu nyttigere er, at de er dynamiske: Du kan klikke på linket for at få information om den kontekst, som variablen er erklæret i (fx om navnerummet System, så som hvor det bliver erklæret, defineret, brugt eller hvad dets dokumentation er) og du kan klikke på det blå link for at få flyttet tekstmarkøren hen til symbolets erklæring (i eksemplet til linje 289 i utilities) eller få en liste over steder, hvor dette symbol bruges i den aktuelle fil eller overalt i projekterne, som hører den aktuelle session. Det sidste er ofte nyttigt, hvis du for eksempel vil undersøge, hvordan en given funktion bruges i en større kodebase.
Note
Note
Information på filniveau
Går vi et niveau op, så kan du få information om hele den aktuelle kildefil ved at placere markøren i en linje på filniveau og se hvad værktøjsvisningen Kodebrowser viser:
Her vises en liste med navnerum, klasser og funktioner, som bliver erklæret eller defineret i den akuelle fil. Det giver dig et overblik over, hvad der sker i denne fil og en måde til hoppe direkte til enhver af disse erklæringer eller definitioner uden at skulle rulle op eller ned i filen eller søge efter et bestemt symbol.
Note
Information om projekter og sessioner
Der er mange måder at få information om et helt projekt (eller endda om alle projekter i en session). Den slags information gives som regel i en værktøjsvisning. For eksempel giver værktøjsvisningen Klasser dig en træstruktur over alle klasser og omgivende navnerum for alle projekter i en session sammen med hver enkelt klasses medlemsfunktioner og -variable:
Lader du musen svæve over et emne, så får du igen information om symbolet, hvor det bliver erklæret, defineret og brugt. Dobbeltklikker du på et emne i trævisningen, så åbnes et editorvindue med markøren placeret der, hvor symbolet bliver erklæret eller defineret.
Med der er andre måder at få vist global information. For eksempel giver værktøjsvisningen Dokumenter en oversigt over et projekt i form af de forskellige slags filer eller andre dokumenter, som indgår i projektet:
Bevæg dig rundt i kildekoden
I det forrige afsnit har vi fortalt, hvordan man udforsker kildekoden, dvs. får information om symboler, filer og projekter. Næste skridt er at bevæge sig rundt i kildekoden. Der er igen forskellige niveauer, som det kan foregå på: lokalt, på filniveau og indenfor et helt projekt.
Note
KDevelop er meget mere end en editor, men den er også er kildeeditor. Som sådan kan du selvfølge flytte markøren op, ned og til højre og venstre i kildefilen. Du kan også bruge tasterne PageUp og PageDown og alle de andre kommandoer, som du kender det fra enhver brugbar editor.
På filniveau har KDevelop mange måder at navigere igennem kildekoden på, herunder følgende metoder til at hoppe rundt i en given fil:
- Omrids: Du kan få et overblik over, hvad der er i den aktuelle fil på mindst tre forskellige måder:
- Ved at klikke i tekstboksen øverst til højre i hovedvinduet eller taste Alt + Ctrl + N åbner du en dropned-liste med alle funktions- og klasseerklæringer:
Du kan så vælge at hoppe til en af dem eller — hvis der er mange — begynde at skrive, hvorved listen bliver mindre og mindre efterhånden som de emner, som ikke passer med det du har skrevet forsvinder fra listen. - Placér markøren på i linje på filniveau (dvs. udenfor erklæringer og definitioner af funktioner og klasser) mens værktøjsvisningen Kodebrowser er åben:
Dette giver dig også et oberblik over den aktuelle fil og lader dig vælge, hvor du vil hoppe til. - Lader du musen svæve over fanebladet for en af de åbne filer, så får du også et omrids af filen i dette faneblad.
- Ved at klikke i tekstboksen øverst til højre i hovedvinduet eller taste Alt + Ctrl + N åbner du en dropned-liste med alle funktions- og klasseerklæringer:
- Kildefiler er organiserede som en liste af erklæringer og definitioner af funktioner. Taster du Alt + Ctrl + PgUp eller Alt + Ctrl + PgDown, så hopper du til den forrige eller næste funktionsdefinition i denne fil.
Som nævnt andetsteds arbejder KDevelop normalt ikke men enkelte kildefiler men ser på projekter som et hele (eller snarere med alle de projekter, som er en del af den aktuelle session). Som konsekvens af det giver den dig mange muligheder for at navigere igennem hele projekter. Nogle af disse muligheder er afledt af de funktioner, som vi allerede har omtalt i afsnittet Udforsk kildekoden, mens andre er helt nye. Det fælles tema er, at disse navigationsfunktioner er baseret på en semantisk forståelse af kildekoden, dvs. at hele projekteer med tilhørende data skal parses, for at de skal kunne fungere. Den følgende liste viser nogle af måderne, på hvilke du kan navigere igennem kildekode, som kan være spredt ud over et potentielt meget stort antal filer:
- Som vi så i afsnittet Udforsk kildekoden kan du få et værktøjstip, som forklarer individuelle navnerum, klasser, funktioner og variable ved at lade musen svæve over deres navn eller holde Alt-tasten nede et stykke tid. Her er et eksempel:
Klikker du på linkene for et symbols erklæring eller udvider du listen med anvendelser, så kan du hoppe til disse steder — den relevante fil åbnes, hvis det er nødvendigt — og placere markøren på det tilsvarende sted. En lignende effekt kan opnås ved at bruge værktøjsvisningen Kodebrowser, som også er omtalt tidligere.
- Åbn hurtigt: De forskellige åbn hurtigt-metoder i KDevelop giver dig kraftfulde måder at hoppe til andre filer eller steder. Der er fire af dem:
- Åbn klasse hurtigt ( eller Alt + Ctrl + C): Du vil få en liste med alle klasserne i denne session. Når du begynd at skrive (en del af) klassens navn, så skrumper listen ind til kun at indeholde de klasser, hvis navne matcher det, som du har skrevet indtil nu. Når listen er kort nok, så kan du vælge et element ved brug af pil op- og ned-tasterne og KDevelop vil tage dig til det sted, hvor klassen bliver erklæret.
- Åbn funktion hurtigt ( eller Alt + Ctrl + M): Du vil få en liste med alle (medlems)funktionerne, som indgår i projekterne i den aktuelle session, og du kan vælge fra listen på samme måde som ovenfor. Bemærk, at listen kan inkludere både funktionserklæringer og -definitioner.
- Åbn fil hurtigt ( eller Alt + Ctrl + O): Du vil få en liste med alle filerne, som indgår i projekterne i den aktuelle session, og du kan vælge fra listen på samme måde som ovenfor.
- Universel åbn hurtigt ( eller Alt + Ctrl + Q): Hvis du glemmer, hvilken tastaturgenvej, der er bundet til hvilken af de foregående metoder, så er dette den universelle schweizerkniv — den giver dig en liste med alle filer, funktioner, klasser og andre ting, som du kan vælge fra.
- Hop til erklæring eller definition, skift imellem def/erkl
Note
- Switch between declaration/definition: In the example above, to jump to the site of the declaration of the current function, you need to first place the cursor on the function name. To avoid this step, you can select (or hit Shift + Ctrl + C) to jump to the declaration of the function within which the cursor currently is. Selecting the same menu entry a second time transports you back to the place where the function is defined.
- næste/forrige anvendelse
Note
- Kontekstlisten: Webbrowsere har en funktion, hvor du kan gå frem og tilbage i listen over de senest besøgte sider. KDevelop har den samme slags funktion, hvor du istedet for websider besøger kontekster. En kontekst er markørens aktuelle position, og du ændrer konteksten ved enhver form for navigering bortset fra markørkommandoerne — for eksempel ved at klikke på et link i et værktøjstip eller i værktøjsvisningen Kodebrowser, vælge et punkt i menuen eller bruge en af de andre navigationskommandoer. Brug menuerne (Meta + pil til venstre) og (Meta + pil til højre) til at gå igennem listen af besøgte kontekster ligesom - og -knapperne i en browser fører dig frem og tilbage i listen af besøgte websider.
- class view
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; }; 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:
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
Ctrl+Space to open a list of completions manually.
Adding new classes and implementing member functions
KDevelop has a wizard for adding new classes. To add a new class, select to get the following dialog box:
Here, we have entered the new class's name Bus (you can also enter here which other classes this class should be derived from). The next page of the dialog allows us to select the standard member functions we will need:
Here, we want a default constructor, a copy constructor, and a destructor. After the following pages of the dialog that allow you to select a license header and the location for the new files, KDevelop will generate two new tabs with the header and source files:
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 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 .) 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 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
Note
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 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 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 (or right clicking on the name and selecting ). 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<dim,spacedim>::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 the button with the green + to add a snippet, to get a dialog like the following:
Note
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
Tilstande og arbejdssæt
Hvis du er kommet så langt, så se lidt på øverste højre hjørne af KDevelops hovedvindue. Som det ses i billedet finder du her de tre tilstande, som KDevelop kan være i: (den tilstand, som vi diskuterer i dette kapitel om arbejdet med kildekoden), (se Fejlsøgning af programmer) og (se Arbejdet med versionskontrolsystemer).
Hver tilstand har sit eget sæt af værktøjer i vindueskanten og sit eget arbejdssæt af aktuelt åbne filer og dokumenter. Desuden er hvert arbejdssæt knyttet til en session, svarende til den sammenhæng, der vises i billedet ovenfor. Bemærk, at filerne i arbejdssættet hører til samme session med kan komme fra forskellige projekter, som hører til samme session.
Hvis du åbner KDevelop for første gang, så er arbejdssættet tomt — der er ingen åbne filer. Men idet du åbner filer for redigering (eller fejlsøgning eller eftersyn i de andre tilstande), så vokser dit arbejdssæt. Som du kan se på billedet herunder, så viser et symbol i fanebladet at arbejdssættet ikke er tomt. Bemærk, at nå du lukker KDevelop, gemmes arbejdssættet og det genetableres, når du genstarter programmet, dvs. at du får det samme sæt af åbne filer.
Hvis du lader musen svæve over symbolet for et arbejdssæt, så dukker der et værktøjstip frem, som viser dig hvilke filer, der aktuelt er åbne i dette arbejdssæt (her filerne step-32.cc og step-1.cc). Klikker du på det røde minustegn, så lukkes fanebladet med den tilsvarende fil. Klikker du på , så lukkes hele arbejdssættet på en gang (dvs. alle åbne filer lukkes). Pointen med at lukke et arbejdssæt er, at det ikke bare lukker alle filer men faktisk gemmer det og åbner et nyt, endnu tomt sæt. Det kan du se her:
Bemærk de to symboler til venstre for det tre tilstandsfaneblade (hjertet og det uidentificérbare symbol til venstre for det). Hver af disse symboler repræsenterer et gemt arbejdssæt. Hvis du lader musen svæve over hjertesymbolet, så ser du noget i retning af dette:
Det viser dig, at det tilsvarende arbejdssæt indeholder to filer og deres tilsvarende projektnavne: Makefile og changes.h. Klikker du på , så gemmes og lukkes det aktuelle arbejdssæt (i eksemplet her har det filerne tria.h og tria.cc åbne) og åbner i stedet det valgte arbejdssæt. Du kan også slette et arbejdssæt permanent.
Nogle nyttige tastaturgenveje
KDevelops editor bruger standard-tastaturgenveje til alle almindelige redigeringsoperationer. Den understøtter dog også et antal mere avancerede operationer, når man redigerer kode; nogle af disse er bundet til forskellige tastekombinationer. De følgende er ofte nyttige:
| Jumping around in code | |
|---|---|
| Ctrl+Alt+O | Quick open file: enter part of a filename and select among all the files in the current session's projects' directory trees that match the string; the file will then be opened |
| Ctrl+Alt+C | Quick open class: enter part of a class name and select among all class names that match; the cursor will then jump to the class declaration |
| Ctrl+Alt+M | Quick open function: enter part of a (member) function name and select among all names that match; note that the list shows both declarations and definitions and the cursor will then jump to the selected item |
| Ctrl+Alt+Q | Universal quick open: type anything (file name, class name, function name) and get a list of anything that matches to select from |
| Ctrl+Alt+N | Outline: Provide a list of all things that are happening in this file, e.g. class declarations and function definitions |
| Ctrl+, | Jump to definition of a function if the cursor is currently on a function declaration |
| Ctrl+. | Jump to declaration of a function or variable if the cursor is currently in a function definition |
| Ctrl+Alt+PageDown | Jump to next function |
| Ctrl+Alt+PageUp | Jump to previous function |
| Ctrl+G | Goto line |
| Searching and replacing | |
| Ctrl+F | Find |
| F3 | Find next |
| Ctrl+R | Replace |
| Ctrl+Alt+F | Find-Replace in multiple files |
| Other things | |
| Ctrl+_ | Collapse one level: remove this block from view, for example if you want to focus on the bigger picture within a function |
| Ctrl++ | Expand one level: undo the collapsing |
| Ctrl+D | Comment out selected text or current line |
| Ctrl+Shift+D | Comment in selected text or current line |
| Alt+Shift+D | Document the current function. If the cursor is on a function or class declaration then hitting this key will create a doxygen-style comment pre-populated with a listing of all parameters, return values, etc. |
| Ctrl+T | Transpose the current and the previous character |
| Ctrl+K | Delete the current line (note: this is not just emacs' "delete from here to the end of the line") |