Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts •...
Transcript of Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts •...
![Page 1: Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts • Theoretical: History of code and comments. Why have comments NOT been talked about](https://reader035.fdocuments.net/reader035/viewer/2022071009/5fc69a61a1191b7cbe7c311f/html5/thumbnails/1.jpg)
Not Your Typical Prose: Documenting Software
By Amy Hunt
![Page 2: Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts • Theoretical: History of code and comments. Why have comments NOT been talked about](https://reader035.fdocuments.net/reader035/viewer/2022071009/5fc69a61a1191b7cbe7c311f/html5/thumbnails/2.jpg)
Documentation
![Page 3: Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts • Theoretical: History of code and comments. Why have comments NOT been talked about](https://reader035.fdocuments.net/reader035/viewer/2022071009/5fc69a61a1191b7cbe7c311f/html5/thumbnails/3.jpg)
The Intersect!
Software Development
Annotation
11 Years
in the Industry
Liberal Studies
![Page 4: Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts • Theoretical: History of code and comments. Why have comments NOT been talked about](https://reader035.fdocuments.net/reader035/viewer/2022071009/5fc69a61a1191b7cbe7c311f/html5/thumbnails/4.jpg)
Terminology
• Software/ [Source] Code • Software Documentation
– Internal Documentation – External Documentation
• Comments/Annotation • Developers/Programmers • Self-Documenting Code (will get to later) • Literate Programming (will get to later)
![Page 5: Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts • Theoretical: History of code and comments. Why have comments NOT been talked about](https://reader035.fdocuments.net/reader035/viewer/2022071009/5fc69a61a1191b7cbe7c311f/html5/thumbnails/5.jpg)
Outline
This thesis has three(3) distinct parts • Theoretical: History of code and
comments. Why have comments NOT been talked about in software studies?
• Qualitative analysis of comments as used in practice using “QDA Miner”
• Reflective: Survey of how programmers think about their source code commenting habits.
![Page 6: Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts • Theoretical: History of code and comments. Why have comments NOT been talked about](https://reader035.fdocuments.net/reader035/viewer/2022071009/5fc69a61a1191b7cbe7c311f/html5/thumbnails/6.jpg)
Abstract
• Comments address future technical audiences and serves to remind the software engineer of earlier decisions
• Writing to your future self isn’t as easy as you think. It’s part didactic, part egotistical, but mostly an essential communication tool.
• While computer languages have intuitive and clear syntax, they were made for the compilers and not the developer; therefore, they still need some human interpretation of what it is doing
![Page 7: Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts • Theoretical: History of code and comments. Why have comments NOT been talked about](https://reader035.fdocuments.net/reader035/viewer/2022071009/5fc69a61a1191b7cbe7c311f/html5/thumbnails/7.jpg)
Code is Open to Interpretation
Machine Code: 01001001 00100000 01101100 01101111 01110110 01100101 00100000 01100011 01101111 01101101 01101101 01100101 01101110 01110100 01110011 00100001
Source Code:
Python 3.2
(‘I Love Comments!’)
#Print comment proclamation #so people know my passion
What? Why?
Compiler
![Page 8: Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts • Theoretical: History of code and comments. Why have comments NOT been talked about](https://reader035.fdocuments.net/reader035/viewer/2022071009/5fc69a61a1191b7cbe7c311f/html5/thumbnails/8.jpg)
Abstract Continued….
• Writing readable code is an art that has been extensively written about – Self-Documenting code – Programmers should be able to read the code
and understand what it is doing – If not, rewrite so it is clearer!
What happens if it’s not clear….
![Page 9: Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts • Theoretical: History of code and comments. Why have comments NOT been talked about](https://reader035.fdocuments.net/reader035/viewer/2022071009/5fc69a61a1191b7cbe7c311f/html5/thumbnails/9.jpg)
Apply Literate Programming
• Donald Knuth (1981) “I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature. “
• A programming language and documentation system.
• Good Code+ Narrative Comments • Almost…
![Page 10: Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts • Theoretical: History of code and comments. Why have comments NOT been talked about](https://reader035.fdocuments.net/reader035/viewer/2022071009/5fc69a61a1191b7cbe7c311f/html5/thumbnails/10.jpg)
Why is it so important?
• Today our world is dominated by rapidly developing technologies that are built on collaboratively developed toolkits. Apps developed for the iPhone or the Android platform, for example, are complex and highly modular.
• Maintaining and sharing code is essential
![Page 11: Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts • Theoretical: History of code and comments. Why have comments NOT been talked about](https://reader035.fdocuments.net/reader035/viewer/2022071009/5fc69a61a1191b7cbe7c311f/html5/thumbnails/11.jpg)
Modularity – Real World Example
READ ME
Model File
View Files
Controller File
Configuration
Set up Scripts
Data File
![Page 12: Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts • Theoretical: History of code and comments. Why have comments NOT been talked about](https://reader035.fdocuments.net/reader035/viewer/2022071009/5fc69a61a1191b7cbe7c311f/html5/thumbnails/12.jpg)
Cooperative Communities • A kind of code digital “commons” • Open Source
– Github – Google Code
• Creating a community of software developers who read and write code
![Page 13: Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts • Theoretical: History of code and comments. Why have comments NOT been talked about](https://reader035.fdocuments.net/reader035/viewer/2022071009/5fc69a61a1191b7cbe7c311f/html5/thumbnails/13.jpg)
Interpretive movement
• Ease of debugging (Maintenance) • Small program size • Comments are visible to all readers and
consumers of the code.
![Page 14: Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts • Theoretical: History of code and comments. Why have comments NOT been talked about](https://reader035.fdocuments.net/reader035/viewer/2022071009/5fc69a61a1191b7cbe7c311f/html5/thumbnails/14.jpg)
Software Studies
Software studies are a series of short studies: “[a] speculative, expository, and critical text on particular digital objects, language, and logical structures.” --Matthew Fuller
![Page 15: Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts • Theoretical: History of code and comments. Why have comments NOT been talked about](https://reader035.fdocuments.net/reader035/viewer/2022071009/5fc69a61a1191b7cbe7c311f/html5/thumbnails/15.jpg)
Source Code Text Retrieval
• QDA Miner is an easy-to-use qualitative data analysis tool for coding, annotating (note features), retrieving and analyzing
• Free Version • Licensed Version • Small learning curve for basic features
√
![Page 16: Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts • Theoretical: History of code and comments. Why have comments NOT been talked about](https://reader035.fdocuments.net/reader035/viewer/2022071009/5fc69a61a1191b7cbe7c311f/html5/thumbnails/16.jpg)
QDA Miner
• 180 Cases thus far… • 3 Variables (attributes to tag each
document) – Language – Audience – Commented
• 30 Codes (strings to retrieve, count, and apply statistical analysis to)
![Page 17: Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts • Theoretical: History of code and comments. Why have comments NOT been talked about](https://reader035.fdocuments.net/reader035/viewer/2022071009/5fc69a61a1191b7cbe7c311f/html5/thumbnails/17.jpg)
QDA Miner
![Page 18: Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts • Theoretical: History of code and comments. Why have comments NOT been talked about](https://reader035.fdocuments.net/reader035/viewer/2022071009/5fc69a61a1191b7cbe7c311f/html5/thumbnails/18.jpg)
Survey Says…
• Comment on Comments • Anonymous • Message Boards/Word of Mouth • 10 Questions/4 general categories
– Demographical – Academic Background – Experience – Habits
![Page 19: Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts • Theoretical: History of code and comments. Why have comments NOT been talked about](https://reader035.fdocuments.net/reader035/viewer/2022071009/5fc69a61a1191b7cbe7c311f/html5/thumbnails/19.jpg)
Results
• 168 Programmers • 23 Different Countries • 25 different states in the United States. • The biggest U.S. state representations
were from New Hampshire, New Jersey, and California.
![Page 20: Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts • Theoretical: History of code and comments. Why have comments NOT been talked about](https://reader035.fdocuments.net/reader035/viewer/2022071009/5fc69a61a1191b7cbe7c311f/html5/thumbnails/20.jpg)
Statistics from Survey
86%
12%
0% 2%
Gender
Male
Female
Other
I would rather not say
No 45%
Skipped 28%
Yes, some kind 27%
Formal Training
![Page 21: Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts • Theoretical: History of code and comments. Why have comments NOT been talked about](https://reader035.fdocuments.net/reader035/viewer/2022071009/5fc69a61a1191b7cbe7c311f/html5/thumbnails/21.jpg)
Conclusion
• Developers think they are pretty good at commenting, and generalize other’s comment habits as “poor”
• “Whys” are always better than “hows” • Comments help with comprehension • Literate Programming is a life style change • Automatic documentation generation does helps
![Page 22: Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts • Theoretical: History of code and comments. Why have comments NOT been talked about](https://reader035.fdocuments.net/reader035/viewer/2022071009/5fc69a61a1191b7cbe7c311f/html5/thumbnails/22.jpg)
Misconceptions
• No Tower of Babel for Code/Comments yet!
![Page 23: Not Your Typical Prose - cultcritlab.org · Outline This thesis has three(3) distinct parts • Theoretical: History of code and comments. Why have comments NOT been talked about](https://reader035.fdocuments.net/reader035/viewer/2022071009/5fc69a61a1191b7cbe7c311f/html5/thumbnails/23.jpg)
Thank you!
• Comments? J • Questions?