{"id":17972,"date":"2022-07-11T14:11:09","date_gmt":"2022-07-11T12:11:09","guid":{"rendered":"https:\/\/magazine.swissinformatics.org\/?p=17972"},"modified":"2023-06-01T09:41:09","modified_gmt":"2023-06-01T07:41:09","slug":"the-curious-case-of-software-documentation","status":"publish","type":"post","link":"https:\/\/magazine.swissinformatics.org\/fr\/the-curious-case-of-software-documentation\/","title":{"rendered":"The Curious Case of Software Documentation"},"content":{"rendered":"\n
\"Illustrative<\/figure>\n\n\n\n

Many programmers share the viewpoint \u201ccode is documentation enough\u201d and do not invest time and effort into documenting their code. However, absent software documentation often is a sign of cognitive biases and poor management practices, rather than source code clarity. In turn, such attitude leads to an increase of cognitive load on programmers during program comprehension and maintenance, and poorer software quality overall.<\/em>
\nA number of solutions for docs generation and referencing support the programmers in the documentation effort, though their adoption is not high and their applicability is not universal. Now we still depend on the first code author to document the what, the how, and the why of their code. And more so in the documentation than in the code itself.<\/em><\/p>\n\n\n\n

In engineering and manufacturing, documentation accompanies the product during all of its life cycle. Typically, development begins with the design documentation. During product creation a blueprint becomes a bridge, a circuit diagram \u2014 a fitness tracker, a sequence of pictograms \u2014 yet another IKEA shelf, that weird sequence of abbreviations and a ball of yarn \u2013 a sweater, and so the list goes. After the product is released, the use and maintenance documentation come into play. The goal of all these manuals, care instructions, diagnostics and repair leaflets is simple \u2014 to make clear what the product is, how to use it, and how to repair or adjust it.
\nYou might expect the same for software products \u2014 after all, the creation process is called software engineering. Yet the software engineers often are the very first people to forgo the documentation and some even argue that since the source code can be read and inspected directly, there is no need to explain it more, both when we are talking about internal documentation for other developers (e.g., source code comments, API interface documentation), and external one (like help pages and user manuals).<\/p>\n\n\n\n

In 1976 Niklaus Wirth, a world-famous Swiss computer scientist, published one of the books that have been influencing the education of all generations of programmers since: \u201cAlgorithms + Data structures = Programs\u201d. And while the book was great at the time to teach about algorithm design and data structure implementation, its primary goal was not to encompass the whole software development life cycle (SDLC). Computer programs do not exist in vacuum; they are written to process, generate, or otherwise manipulate data \u2013 which, in turn, has noise, gaps, or just sometimes does not match the initial expectations. So, while there are some initial assumptions taken during the software design phase about the data and the program\u2019s expected behavior on it, it is the actual behavior in presence of the data that matters. The actual behavior is something that is observed, documented, adjusted, and the knowledge accumulated along the way is passed to each subsequent person working on that program.<\/p>\n\n\n\n

And even in passing the knowledge on there are discrepancies, as a recent (2016) study by P. W. McBurney and C. McMillan shows [1]. The authors looked into the content of source code descriptive summaries within the comments, and discovered that first code authors write more about what the code does and why, keeping the focus on the \u201cbig picture\u201d (and the expected program behavior), whereas all subsequent authors, who had to work with the same code, concentrated on the how part, leaving notes about interaction of the program components between themselves (the actual behavior), but not expanding the problem domain knowledge already present in the comments.<\/p>\n\n\n\n

So why don\u2019t programmers document their code consistently?<\/h4>\n\n\n\n

Several factors come into play here.<\/p>\n\n\n\n

It does not seem necessary<\/h5>\n\n\n\n

One is the cognitive bias known as \u201cthe curse of knowledge\u201d. I like the simple explanation of it on Wikipedia: \u201ca cognitive bias that occurs when an individual, who is communicating with other individuals, assumes they have the background knowledge to understand\u201d. In software development this translates directly into \u201cI can understand my code [now] therefore it is clear enough for everyone else to understand\u201d. The illusion of universal understanding does not take into account the hours spent on studying the problem domain and building an abstract model of it (and a quite a subjective model). Neither does it include additional hours spent on actually engineering, when understanding of the data and control flow accumulate and allow the developer to model the execution of the source code inside her head.<\/p>\n\n\n\n

It seems to be there already<\/h5>\n\n\n\n

Another contributing factor is the similarity of source code to natural text in most cases nowadays. If we go back to the \u201cgood ol\u2019 days\u201d of first computers and punched cards, the actual executable code looked like sequences of holes in thick paper, and just looking at them would not give you much knowledge. Assembly languages, being the next evolution step, were a bit more human-readable, yet still involved dual thought flow \u2013 both program algorithm (the why, typically written in comments) and the way it is executed on a specific hardware architecture (concrete instruction sets comprising the how). Some decades later high-level and general-purpose programming languages and their compilers matured, with their syntax becoming more suitable to express abstract data structures and algorithms almost at the level of problem domain abstractions, and the work of translating these notations to actual, executable machine code was delegated to specialized software, the compiler. Nowadays high-level programming languages come in many flavors, allowing to write programs either in a quite verbose imperative way, focusing on execution steps, or one can opt for functional programming languages and express oneself closer to mathematical models underlying the software solution as possible, or focus on expressing the execution as logic propositions, or even go for all of it \u2013 one of the recent trends in software development is polyglot systems. This high-level code at times can look very similar to natural language \u2013 but it is not. You can even think of it as a foreign language, for which you do not have the dictionary (the documentation). You\u2019ll get its meaning eventually, yes, but how much time would you need?<\/p>\n\n\n\n

And, as usual, there is no time<\/h5>\n\n\n\n

And like with any engineering projects, poor management, be it individual or team one, has a very strong impact on documentation presence and quality. It has become a poor standard practice to value executable code more than its documentation \u2013 and as soon as the former is operational enough, the developers urge to continue with other implementation tasks. Plus, chances are the first team working on the code will not be the one supporting the code later thanks to the growing adoption of developer outsourcing\/outstaffing business practice. Documentation writing takes time, and if the budget is tight, it is one of the first things to let go.<\/p>\n\n\n\n

The actual cost of not documenting the code<\/h4>\n\n\n\n

Documentation is still produced, but indirectly, and it just costs all of us.<\/p>\n\n\n\n

It costs oneself in the first place<\/h5>\n\n\n\n

Most textbooks and lectures on software development, when talking about the software development life cycle, will repeat over and over that most of the program lifetime is spent not in the development phase \u2013 but in the maintenance one. And a big part of the maintenance process is spent in an activity called  \u201cprogram comprehension\u201d \u2013 basically, reading the code to understand what it does. A study from 2018 by Xia et al. [2] finds that \u201con average developers spend ~58 percent of their time on program comprehension activities, and that they frequently use web browsers and document editors to perform program comprehension activities.\u201d. Let that sink in: almost 2 minutes out of every 3 for just understanding the source code.<\/p>\n\n\n\n

It costs the developer community<\/h5>\n\n\n\n

While the development team might release the software product on the market without complete documentation, people will still look for it, as the study above indicates. StackOverflow [3], a \u201cpublic platform building the definitive collection of coding questions & answers\u201d is one of the resources developers use most (yes, I rely on it, too). Who writes the answers and the examples? The community. In their free time, in their work time, in their study time. A more entertaining \u201csecond shift\u201d, if you ask me, also unpaid though somewhat more recognized. Additionally, community-sourced documentation has certain advantages for software products growth, as the NumPy case study [4] shows, one of the contributing factors being the diversity of the community members [5]. Yet documentation quality concerns still remain: how up to date and correct will such documentation be? Moreover, accessibility of the documentation de facto being hosted on a separate resource is definitely not optimal.<\/p>\n\n\n\n

It costs the end users too<\/h5>\n\n\n\n

Poorly documented code, that is harder to understand, is also harder to test and control for quality, especially under the usual tight time pressure (have I already mentioned poor management?). As a result, errors and bugs in the software propagate into the real world, causing spacecraft crashes (think of the Mars Climate Orbiter crashing due to one part of the code processing the sensor data in metric and another in imperial units), medical equipment doing more harm than good and leading to patient deaths (Therac-25 radiation therapy device and race conditions during software safety checks), and many more \u2013 numerous articles on \u201cN worst computer bugs in history\u201d might give you some ideas how far it can go.<\/p>\n\n\n\n

Solutions?<\/h4>\n\n\n\n

Nobody will argue that producing documentation is easy. We, scientists and practitioners, are still working on the tool support for it, to lessen this burden. So, while there is no one solution (and likely there will never be), several existing ones can be combined in most cases.<\/p>\n\n\n\n

Increasing code readability for humans<\/h5>\n\n\n\n

One of the efforts the practitioner community has offered are guidelines and conventions on meaningfully naming, structuring, formatting, and also documenting the source code. The benefits of following those guidelines are having a more uniform code base, which is critical when numerous different people contribute over disjoint periods of time. Good news is that programmers do tend to follow the guidelines, especially the parts about the content, documenting their knowledge. Not so good news is that the code linter tool support for documentation conformance to guideline standards focuses instead mostly on the formatting of that documentation [6].<\/p>\n\n\n\n

Adding more code still: testing<\/h5>\n\n\n\n

Some would argue that code is enough to understand the algorithms, and tests are enough to showcase the API use and both expected and undesirable program executions. There might even be enough tests written to account of edge cases. And testing frameworks greatly help in automating test case generation and execution. Moreover, the team might be following a development approach that prioritizes the tests from the beginning \u2013 like test- or behavior-driven development (TDD or BDD, respectively). However, this approach in principle is incomplete \u2013 producing a test suite that will consider all possible executions for all program units will require too much effort, and additionally at times testing in the eyes of management falls into the same category as documentation \u2013 barest minimum possible. Please refer above again to the part about bugs having real world consequences.<\/p>\n\n\n\n

Adding formal contracts: between code and text<\/h5>\n\n\n\n

Some programming languages allow attaching contracts or assertions of some sort to specific methods and program points. Contracts are executable specifications that typically contain properties of program constructs: is this variable non-null, is this array sorted, is this array index always within the array\u2019s boundaries, etc. They complement the type systems in typed languages (think of C++ and Java) and can provide some additional correctness checks in the untyped languages (think of Python). Just like with tests, contracts are executed by specialized verification frameworks. One big advantage of using them is that unlike tests they allow for completeness, as the verification framework analyses whether the contract holds or not for all possible executions. However, adoption of contracts is still low due to the factors like (a) additional cost for a developer to learn a new formalism \u2013 the contract language, (b) limited to low-level expressiveness of the properties that can be included to the contract: signs and value ranges of numeric variables, array properties, nullness of pointers and variables, (c) program analyses to prove that those properties hold or not are extremely hard to develop.<\/p>\n\n\n\n

Generating documentation<\/h5>\n\n\n\n

Modern interactive development environments (IDEs) allow to generate documentation stubs, or templates to be filled with text. In theory, another tool, a code linter, will be able to check if the comment is still empty and notify the programmer, asking to improve the documentation. In practice, however, some linters will just check if a comment is present, so even an empty one will satisfy the check.
\nAs for generating documentation automatically from the source code, the problem known in the software engineering researcher community as \u201csoftware summarization\u201d, the research to date has mainly focused around one issue: the code itself does not contain enough information (=is not enough!) to produce natural language text that is meaningful to humans. Dozens of publications over the past two decades center on addressing the problem of how to get the relevant context information. Successful prototype documentation generators rely on outputs of static analyses, using natural language information in the program identifiers, tracing high-level project documentation with information retrieval methods, and using human-produced templates as a base to be filled with that information.<\/p>\n\n\n\n

Developing both code and documentation simultaneously<\/h5>\n\n\n\n

Another approach to having the documentation for the code is to evolve the code and the docs simultaneously, intertwining them, and treating them both as equally important software components (which seems natural given that high-level programming languages designed for human readability dominate the software development technology market). One good example here is the gradual adoption of the \u201clive documentation\u201d technology in agile software development, mostly in the teams applying a behavior-driven development workflow. Here, with some additional tool support, programmers can create high-level documentation \u2013 like requirement documents with domain concepts \u2013 and link them to the executable source code directly. More commonly though the domain model and the development-specific information will reside in an internal wiki-like format; example software solutions being Confluence, GitLab, Phabricator, or Notion, and the links to the source code will be added manually.
\nIn the same category falls literate programming, a paradigm introduced by Donald Knuth, another world-famous American computer scientist, in 1984. The main idea behind it is to follow the natural flow and expression of human thought, and support it with program execution, and not the other way around, where constraints and order of program execution guide the thought. A well-known example of such programs is JuPyter notebooks \u2013 interactive environments capable of processing text documents containing source code snippets in them.<\/p>\n\n\n\n

And now the cherry on the top:<\/p>\n\n\n\n

Documentation is code enough (Good news everyone!)<\/h4>\n\n\n\n

And we might have been solving the wrong problem all this time.<\/p>\n\n\n\n

Even the simplest case of documentation, the source code comments, if written with enough detail can guide automated code generation rather successfully. A prominent example is GitHub Copilot [7], a code auto-complete tool which relies on a neural network trained on documented source code. While its intended use is primarily aiding the programmers in source code writing, the tool is able to generate snippets based on the comment given by a programmer.
\nProcessing natural language information to improve source code overall turns out to work much better than trying to get anything from the source code by itself [8]. Slowly but surely documentation becomes an indispensable information source also for program analysis [9] and software testing automation [10]. The core idea here is quite simple: natural language used in the technical texts is rather restricted both in its vocabulary and in the use of grammatical structures. So as long, as specific patterns like \u201cX is not null\u201d can be reliably extracted, they can be turned into executable pieces of test source code or verification contracts.<\/p>\n\n\n\n

References and links<\/h4>\n\n\n\n

Please note that preprints of all the papers mentioned below are typically available for free personal use on the web pages of the authors.<\/em><\/p>\n\n\n\n

[1] P. W. McBurney, C. McMillan (2016): \u201cAn empirical study of the textual similarity between source code and source code summaries\u201d. Empirical Software Engineering<\/em> 21, <\/strong>17\u201342. https:\/\/doi.org\/10.1007\/s10664-014-9344-6<\/a><\/p>\n\n\n\n

[2] X. Xia, L. Bao, D. Lo, Z. Xing, A. E. Hassan and S. Li (2018): \u201cMeasuring Program Comprehension: A Large-Scale Field Study with Professionals\u201d. IEEE Transactions on Software Engineering<\/em> 44<\/strong>(10), 951\u2013976. https:\/\/doi.org\/10.1109\/TSE.2017.2734091<\/a><\/p>\n\n\n\n

[3] https:\/\/stackoverflow.com\/<\/a><\/p>\n\n\n\n

[4] A. Pawlik, J. Segal, H. Sharp and M. Petre (2015): \u201cCrowdsourcing Scientific Software Documentation: A Case Study of the NumPy Documentation Project\u201d. Computing in Science & Engineering <\/em>17<\/strong>(1), 28\u201336. https:\/\/doi.org\/10.1109\/MCSE.2014.93<\/a>.<\/p>\n\n\n\n

[5] B. Vasilescu, D.Posnett, B. Ray, M. G. J. van den Brand, A. Serebrenik, P. Devanbu, and V. Filkov (2015): \u201cGender and Tenure Diversity in GitHub Teams\u201d. In  33rd Annual ACM Conference on Human Factors in Computing Systems<\/em>. https:\/\/doi.org\/10.1145\/2702123.2702549<\/a><\/p>\n\n\n\n

[6] P. Rani, S. Abukar, N. Stulova, A. Bergel and O. Nierstrasz (2021). \u201cDo Comments follow Commenting Conventions? A Case Study in Java and Python\u201d. In 21st IEEE International Working Conference on Source Code Analysis and Manipulation, <\/em>pp. 165\u2013169. https:\/\/dx.doi.org\/<\/a>10.1109\/SCAM52516.2021.00028<\/a><\/p>\n\n\n\n

[7] https:\/\/copilot.github.com\/<\/a><\/p>\n\n\n\n

[8] M. D. Ernst (2017): \u201cNatural language is a programming language: Applying natural language processing to software development\u201d. In 2nd Summit on Advances in Programming Languages, <\/em>https:\/\/dx.doi.org\/10.4230\/LIPIcs.SNAPL.2017.4<\/a><\/p>\n\n\n\n

[9] Y. Zhou, R. Gu, T. Chen, Z. Huang, S. Panichella and H. Gall (2017): \u201cAnalyzing APIs Documentation and Code to Detect Directive Defects\u201d. In 39th International Conference on Software Engineering.<\/em> https:\/\/doi.org\/10.1109\/ICSE.2017.11<\/a><\/p>\n\n\n\n

[10] A. Blasi, A. Goffi, K. Kuznetsov, A. Gorla, M. D. Ernst, M. Pezz\u00e8, and S. Delgado Castellanos (2018): \u201cTranslating Code Comments to Procedure Specifications\u201d<\/em>. In 27th ACM SIGSOFT International Symposium on Software Testing and Analysis<\/em>. https:\/\/doi.org\/10.1145\/3213846.3213872<\/a><\/p>\n\n\n\n

\"Nataliia<\/figure>\n\n\n\n

Dr. Nataliia Stulova<\/strong> is a software engineer and a computer science researcher with 10+ years of experience in software analysis and development. Born in Dnipro, Ukraine, she kept the family tradition of the previous two generations to work in STEM, but went for IT instead of rocket engineering. In her scientific work she has been focusing on developing tools to keep software and its specifications aligned at different SDLC stages. She works with software requirement documents, source code comments, and formal program specifications, combining and matching the information in them to ensure program and its documentation correctness. During her time in Switzerland she had collaborated with scientists from EPFL, University of Bern, and ZHAW.<\/p>\n","protected":false},"excerpt":{"rendered":"

Many programmers share the viewpoint \u201ccode is documentation enough\u201d and do not invest time and effort into documenting their code. However, absent software documentation often is a sign of cognitive biases and poor management practices, rather than source code clarity. In turn, such attitude leads to an increase of cognitive load on programmers during program […]<\/p>\n","protected":false},"author":1997,"featured_media":17964,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[4871,468,4877],"tags":[],"yoast_head":"\nThe Curious Case of Software Documentation - SI Digital Magazine<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/magazine.swissinformatics.org\/fr\/the-curious-case-of-software-documentation\/\" \/>\n<meta property=\"og:locale\" content=\"fr_FR\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"The Curious Case of Software Documentation - SI Digital Magazine\" \/>\n<meta property=\"og:description\" content=\"Many programmers share the viewpoint \u201ccode is documentation enough\u201d and do not invest time and effort into documenting their code. However, absent software documentation often is a sign of cognitive biases and poor management practices, rather than source code clarity. In turn, such attitude leads to an increase of cognitive load on programmers during program […]\" \/>\n<meta property=\"og:url\" content=\"https:\/\/magazine.swissinformatics.org\/fr\/the-curious-case-of-software-documentation\/\" \/>\n<meta property=\"og:site_name\" content=\"SI Digital Magazine\" \/>\n<meta property=\"article:publisher\" content=\"https:\/\/www.facebook.com\/www.swissinformatics.org\/?fref=ts\" \/>\n<meta property=\"article:published_time\" content=\"2022-07-11T12:11:09+00:00\" \/>\n<meta property=\"article:modified_time\" content=\"2023-06-01T07:41:09+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/magazine.swissinformatics.org\/wp-content\/uploads\/2022\/07\/code-and-comments-illustration.png\" \/>\n\t<meta property=\"og:image:width\" content=\"981\" \/>\n\t<meta property=\"og:image:height\" content=\"323\" \/>\n\t<meta property=\"og:image:type\" content=\"image\/png\" \/>\n<meta name=\"author\" content=\"Nataliia Stulova\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:creator\" content=\"@SIGesellschaft\" \/>\n<meta name=\"twitter:site\" content=\"@SIGesellschaft\" \/>\n<meta name=\"twitter:label1\" content=\"\u00c9crit par\" \/>\n\t<meta name=\"twitter:data1\" content=\"Nataliia Stulova\" \/>\n\t<meta name=\"twitter:label2\" content=\"Dur\u00e9e de lecture estim\u00e9e\" \/>\n\t<meta name=\"twitter:data2\" content=\"14 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"Article\",\"@id\":\"https:\/\/magazine.swissinformatics.org\/fr\/the-curious-case-of-software-documentation\/#article\",\"isPartOf\":{\"@id\":\"https:\/\/magazine.swissinformatics.org\/fr\/the-curious-case-of-software-documentation\/\"},\"author\":{\"name\":\"Nataliia Stulova\",\"@id\":\"https:\/\/magazine.swissinformatics.org\/en\/#\/schema\/person\/e2a474d6a196f010d39ffed525f90985\"},\"headline\":\"The Curious Case of Software Documentation\",\"datePublished\":\"2022-07-11T12:11:09+00:00\",\"dateModified\":\"2023-06-01T07:41:09+00:00\",\"mainEntityOfPage\":{\"@id\":\"https:\/\/magazine.swissinformatics.org\/fr\/the-curious-case-of-software-documentation\/\"},\"wordCount\":3045,\"commentCount\":0,\"publisher\":{\"@id\":\"https:\/\/magazine.swissinformatics.org\/en\/#organization\"},\"articleSection\":[\"\u2022 Article \u2022\",\"Technologie\",\"ZZ_EditorPick\"],\"inLanguage\":\"fr-FR\",\"potentialAction\":[{\"@type\":\"CommentAction\",\"name\":\"Comment\",\"target\":[\"https:\/\/magazine.swissinformatics.org\/fr\/the-curious-case-of-software-documentation\/#respond\"]}]},{\"@type\":\"WebPage\",\"@id\":\"https:\/\/magazine.swissinformatics.org\/fr\/the-curious-case-of-software-documentation\/\",\"url\":\"https:\/\/magazine.swissinformatics.org\/fr\/the-curious-case-of-software-documentation\/\",\"name\":\"The Curious Case of Software Documentation - SI Digital Magazine\",\"isPartOf\":{\"@id\":\"https:\/\/magazine.swissinformatics.org\/en\/#website\"},\"datePublished\":\"2022-07-11T12:11:09+00:00\",\"dateModified\":\"2023-06-01T07:41:09+00:00\",\"breadcrumb\":{\"@id\":\"https:\/\/magazine.swissinformatics.org\/fr\/the-curious-case-of-software-documentation\/#breadcrumb\"},\"inLanguage\":\"fr-FR\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/magazine.swissinformatics.org\/fr\/the-curious-case-of-software-documentation\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/magazine.swissinformatics.org\/fr\/the-curious-case-of-software-documentation\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/magazine.swissinformatics.org\/en\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"The Curious Case of Software Documentation\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/magazine.swissinformatics.org\/en\/#website\",\"url\":\"https:\/\/magazine.swissinformatics.org\/en\/\",\"name\":\"SI Digital Magazine\",\"description\":\"News - Nachrichten - Nouvelles - Notizie\",\"publisher\":{\"@id\":\"https:\/\/magazine.swissinformatics.org\/en\/#organization\"},\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/magazine.swissinformatics.org\/en\/?s={search_term_string}\"},\"query-input\":\"required name=search_term_string\"}],\"inLanguage\":\"fr-FR\"},{\"@type\":\"Organization\",\"@id\":\"https:\/\/magazine.swissinformatics.org\/en\/#organization\",\"name\":\"Swiss Informatics Society\",\"url\":\"https:\/\/magazine.swissinformatics.org\/en\/\",\"logo\":{\"@type\":\"ImageObject\",\"inLanguage\":\"fr-FR\",\"@id\":\"https:\/\/magazine.swissinformatics.org\/en\/#\/schema\/logo\/image\/\",\"url\":\"https:\/\/magazine.swissinformatics.org\/wp-content\/uploads\/2017\/11\/SI_KeyImage_4to3.jpg\",\"contentUrl\":\"https:\/\/magazine.swissinformatics.org\/wp-content\/uploads\/2017\/11\/SI_KeyImage_4to3.jpg\",\"width\":1441,\"height\":1081,\"caption\":\"Swiss Informatics Society\"},\"image\":{\"@id\":\"https:\/\/magazine.swissinformatics.org\/en\/#\/schema\/logo\/image\/\"},\"sameAs\":[\"https:\/\/www.facebook.com\/www.swissinformatics.org\/?fref=ts\",\"https:\/\/twitter.com\/SIGesellschaft\",\"https:\/\/www.youtube.com\/channel\/UCYUEr1Qkbri9GDTa84z415g\"]},{\"@type\":\"Person\",\"@id\":\"https:\/\/magazine.swissinformatics.org\/en\/#\/schema\/person\/e2a474d6a196f010d39ffed525f90985\",\"name\":\"Nataliia Stulova\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"fr-FR\",\"@id\":\"https:\/\/magazine.swissinformatics.org\/en\/#\/schema\/person\/image\/\",\"url\":\"https:\/\/secure.gravatar.com\/avatar\/c64d8f574c7d0ad5db5271bc09d8b65c?s=96&d=mm&r=g\",\"contentUrl\":\"https:\/\/secure.gravatar.com\/avatar\/c64d8f574c7d0ad5db5271bc09d8b65c?s=96&d=mm&r=g\",\"caption\":\"Nataliia Stulova\"},\"description\":\"Dr. Nataliia Stulova is a software engineer and a computer science researcher with 10+ years of experience in software analysis and development. Born in Dnipro, Ukraine, she kept the family tradition of the previous two generations to work in STEM, but went for IT instead of rocket engineering. In her scientific work she has been focusing on developing tools to keep software and its specifications aligned at different SDLC stages. She works with software requirement documents, source code comments, and formal program specifications, combining and matching the information in them to ensure program and its documentation correctness. During her time in Switzerland she had collaborated with scientists from EPFL, University of Bern, and ZHAW.\",\"url\":\"https:\/\/magazine.swissinformatics.org\/fr\/author\/stulova\/\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"The Curious Case of Software Documentation - SI Digital Magazine","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/magazine.swissinformatics.org\/fr\/the-curious-case-of-software-documentation\/","og_locale":"fr_FR","og_type":"article","og_title":"The Curious Case of Software Documentation - SI Digital Magazine","og_description":"Many programmers share the viewpoint \u201ccode is documentation enough\u201d and do not invest time and effort into documenting their code. However, absent software documentation often is a sign of cognitive biases and poor management practices, rather than source code clarity. In turn, such attitude leads to an increase of cognitive load on programmers during program […]","og_url":"https:\/\/magazine.swissinformatics.org\/fr\/the-curious-case-of-software-documentation\/","og_site_name":"SI Digital Magazine","article_publisher":"https:\/\/www.facebook.com\/www.swissinformatics.org\/?fref=ts","article_published_time":"2022-07-11T12:11:09+00:00","article_modified_time":"2023-06-01T07:41:09+00:00","og_image":[{"width":981,"height":323,"url":"https:\/\/magazine.swissinformatics.org\/wp-content\/uploads\/2022\/07\/code-and-comments-illustration.png","type":"image\/png"}],"author":"Nataliia Stulova","twitter_card":"summary_large_image","twitter_creator":"@SIGesellschaft","twitter_site":"@SIGesellschaft","twitter_misc":{"\u00c9crit par":"Nataliia Stulova","Dur\u00e9e de lecture estim\u00e9e":"14 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"Article","@id":"https:\/\/magazine.swissinformatics.org\/fr\/the-curious-case-of-software-documentation\/#article","isPartOf":{"@id":"https:\/\/magazine.swissinformatics.org\/fr\/the-curious-case-of-software-documentation\/"},"author":{"name":"Nataliia Stulova","@id":"https:\/\/magazine.swissinformatics.org\/en\/#\/schema\/person\/e2a474d6a196f010d39ffed525f90985"},"headline":"The Curious Case of Software Documentation","datePublished":"2022-07-11T12:11:09+00:00","dateModified":"2023-06-01T07:41:09+00:00","mainEntityOfPage":{"@id":"https:\/\/magazine.swissinformatics.org\/fr\/the-curious-case-of-software-documentation\/"},"wordCount":3045,"commentCount":0,"publisher":{"@id":"https:\/\/magazine.swissinformatics.org\/en\/#organization"},"articleSection":["\u2022 Article \u2022","Technologie","ZZ_EditorPick"],"inLanguage":"fr-FR","potentialAction":[{"@type":"CommentAction","name":"Comment","target":["https:\/\/magazine.swissinformatics.org\/fr\/the-curious-case-of-software-documentation\/#respond"]}]},{"@type":"WebPage","@id":"https:\/\/magazine.swissinformatics.org\/fr\/the-curious-case-of-software-documentation\/","url":"https:\/\/magazine.swissinformatics.org\/fr\/the-curious-case-of-software-documentation\/","name":"The Curious Case of Software Documentation - SI Digital Magazine","isPartOf":{"@id":"https:\/\/magazine.swissinformatics.org\/en\/#website"},"datePublished":"2022-07-11T12:11:09+00:00","dateModified":"2023-06-01T07:41:09+00:00","breadcrumb":{"@id":"https:\/\/magazine.swissinformatics.org\/fr\/the-curious-case-of-software-documentation\/#breadcrumb"},"inLanguage":"fr-FR","potentialAction":[{"@type":"ReadAction","target":["https:\/\/magazine.swissinformatics.org\/fr\/the-curious-case-of-software-documentation\/"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/magazine.swissinformatics.org\/fr\/the-curious-case-of-software-documentation\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/magazine.swissinformatics.org\/en\/"},{"@type":"ListItem","position":2,"name":"The Curious Case of Software Documentation"}]},{"@type":"WebSite","@id":"https:\/\/magazine.swissinformatics.org\/en\/#website","url":"https:\/\/magazine.swissinformatics.org\/en\/","name":"SI Digital Magazine","description":"News - Nachrichten - Nouvelles - Notizie","publisher":{"@id":"https:\/\/magazine.swissinformatics.org\/en\/#organization"},"potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/magazine.swissinformatics.org\/en\/?s={search_term_string}"},"query-input":"required name=search_term_string"}],"inLanguage":"fr-FR"},{"@type":"Organization","@id":"https:\/\/magazine.swissinformatics.org\/en\/#organization","name":"Swiss Informatics Society","url":"https:\/\/magazine.swissinformatics.org\/en\/","logo":{"@type":"ImageObject","inLanguage":"fr-FR","@id":"https:\/\/magazine.swissinformatics.org\/en\/#\/schema\/logo\/image\/","url":"https:\/\/magazine.swissinformatics.org\/wp-content\/uploads\/2017\/11\/SI_KeyImage_4to3.jpg","contentUrl":"https:\/\/magazine.swissinformatics.org\/wp-content\/uploads\/2017\/11\/SI_KeyImage_4to3.jpg","width":1441,"height":1081,"caption":"Swiss Informatics Society"},"image":{"@id":"https:\/\/magazine.swissinformatics.org\/en\/#\/schema\/logo\/image\/"},"sameAs":["https:\/\/www.facebook.com\/www.swissinformatics.org\/?fref=ts","https:\/\/twitter.com\/SIGesellschaft","https:\/\/www.youtube.com\/channel\/UCYUEr1Qkbri9GDTa84z415g"]},{"@type":"Person","@id":"https:\/\/magazine.swissinformatics.org\/en\/#\/schema\/person\/e2a474d6a196f010d39ffed525f90985","name":"Nataliia Stulova","image":{"@type":"ImageObject","inLanguage":"fr-FR","@id":"https:\/\/magazine.swissinformatics.org\/en\/#\/schema\/person\/image\/","url":"https:\/\/secure.gravatar.com\/avatar\/c64d8f574c7d0ad5db5271bc09d8b65c?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/c64d8f574c7d0ad5db5271bc09d8b65c?s=96&d=mm&r=g","caption":"Nataliia Stulova"},"description":"Dr. Nataliia Stulova is a software engineer and a computer science researcher with 10+ years of experience in software analysis and development. Born in Dnipro, Ukraine, she kept the family tradition of the previous two generations to work in STEM, but went for IT instead of rocket engineering. In her scientific work she has been focusing on developing tools to keep software and its specifications aligned at different SDLC stages. She works with software requirement documents, source code comments, and formal program specifications, combining and matching the information in them to ensure program and its documentation correctness. During her time in Switzerland she had collaborated with scientists from EPFL, University of Bern, and ZHAW.","url":"https:\/\/magazine.swissinformatics.org\/fr\/author\/stulova\/"}]}},"_links":{"self":[{"href":"https:\/\/magazine.swissinformatics.org\/fr\/wp-json\/wp\/v2\/posts\/17972"}],"collection":[{"href":"https:\/\/magazine.swissinformatics.org\/fr\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/magazine.swissinformatics.org\/fr\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/magazine.swissinformatics.org\/fr\/wp-json\/wp\/v2\/users\/1997"}],"replies":[{"embeddable":true,"href":"https:\/\/magazine.swissinformatics.org\/fr\/wp-json\/wp\/v2\/comments?post=17972"}],"version-history":[{"count":0,"href":"https:\/\/magazine.swissinformatics.org\/fr\/wp-json\/wp\/v2\/posts\/17972\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/magazine.swissinformatics.org\/fr\/wp-json\/wp\/v2\/media\/17964"}],"wp:attachment":[{"href":"https:\/\/magazine.swissinformatics.org\/fr\/wp-json\/wp\/v2\/media?parent=17972"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/magazine.swissinformatics.org\/fr\/wp-json\/wp\/v2\/categories?post=17972"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/magazine.swissinformatics.org\/fr\/wp-json\/wp\/v2\/tags?post=17972"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}