Guidelines for Citing Referenced Material

Introduction

Citation Elements

Citation Contents

Article

Book

Booklet

InBook

InCollection

InProceedings

Manual

MastersThesis

Misc

PhDThesis

Proceedings

TechReport

Unpublished

Citations in the Text

[Author-Initial(s)Year]

as in [Spi97] (single author) or [WKS82] (multiple authors) or [Knu88b] (multiple works for the same author and year).

[Number]

as in [12]. Citations are then numbered by order of occurence in the document or by the order they appear when sorted by the author names.

Supersctipt number

as in¹² numbered as described in the previous case.

Author (year)

as in Spinellis (1997) or Kernighan and Ritchie (1978), or (Knuth 1981). Append a lowercase letter (a, b, c) for multiple works by the same author in the same year. The format Author (year) is used in narrative form as used by Knuth (1983), while the format (Author year) is used when the reference is outside the flow of the text (Knuth 1983). We recomment against using this reference style as it confuses bilbiographic tools without offering any significant benefits.

Citation Formats

• AuthorName(s). Book, volume VolumeNumber of Series. Publisher, Address, editionnumber edition, Month Year. Note.

• AuthorName(s). Book Title, volume VolumeNumber of Series, chapter Chapter appearing in a book, page Pages. Publisher, Address, editionnumber edition, Month Year. Note.

• AuthorName(s). Booklet. HowPublished, Address, Month Year. Note.

• AuthorName(s). Collection title. In EditorName, editor, Booktitle, chapter Chapter appearing in a collection, page Pages. Publisher, Address, Month Year. Note.

• AuthorName(s). Journal article. Journal, VolumeNumber(Number):Pages, Month Year. Note.

• AuthorName(s). Manual. Organization, Address, editionnumber edition, Month Year. Note.

• AuthorName(s). Mastersthesistitle. Master's thesis, School, Address, Month Year. Note.

• AuthorName(s). Miscellaneous item. HowPublished, Month Year. Note.

• AuthorName(s). Paper appearing in proceedings. In EditorName, editor, Proceedings Title, page Pages, Address, Month Year. Organization, Publisher. Note.

• AuthorName(s). PhDThesisTitle. PhD thesis, School, Address, Month Year. Note.

• AuthorName(s). Technical report. Type Number, Institution, Address, Month Year. Note.

• AuthorName(s). Unpublished work. Note, Month Year.

• EditorName, editor. ConferenceProceedingsTitle, Address, Month Year. Organization, Publisher. Note.

Citations to Electronic Data

• medium (e.g. Online (for Internet data), CD-ROM),
• data supplier (e.g. IBM, MIT),
• for Internet data the URL, for other data the filename,
• the date you accessed the data.

Examples:

• Oxford English Dictionary Computer File: On Compact Disc. 2nd ed. CD-ROM. Oxford: Oxford UP, 1992.
• Pritzker, Thomas J. An Early Fragment from Central Nepal. March 17, 1995. Asian Arts.com. URL http://asianart.com/pritzker/pritzker.html. Accessed: 2011-11-22. (Archived by WebCite at http://www.webcitation.org/63NhkqLsO (http://www.webcitation.org/63NhkqLsO).)
• Diomidis Spinellis. Greek character encoding for electronic mail messages. Network Information Center, Request for Comments 1947, May 1996. RFC-1947. Online. Network Information Center. Available http://ds.internic.net/rfc/rfc1947.txt (http://ds.internic.net/rfc/rfc1947.txt). 23 March 1998.

Advice for Writing BibTeX Entries

• The work's title is set in title case (http://en.wikipedia.org/wiki/Letter_case#Headings_and_publication_titles), e.g. The Vitamins Are in My Fresh California Raisins. According to the actual style used, the words set with their first letter in uppercase will remain so, or will be converted to lowercase.
• Set the capital letters of proper nouns and acronyms on curly braces, so that they will remain in uppercase, even if the bibliography style is to convert them to lowercase. Example: Cognitive support, {UML} adherence, and {XMI} interchange in {A}rgo/{UML}.
• Ensure that the author names are given either in the form FirstName LastName or LastName, FirstName.
• Author names should be separated with and.
• If the entry contains non-ASCII characters, use the appropriate TeX escapes (http://www.ctan.org/tex-archive/info/symbols/comprehensive/symbols-a4.pdf). Example

  author = {Yann-Ga\"{e}l Gu\'{e}h\'{e}neuc and Herv\'{e} Albin-Amiot},
    

• Change journal names according to the macro file you are using. For instance, write

  	journal = cacm,
    

  instead of

  	journal = "Communications of the ACM",
    

  This allows you to uniformly abbreviate the journal titles, according to the publisher's style. For this to work, you'll need a list of journal abbreviations, like this or this (http://ftp.math.utah.edu/pub//tex/bib/journal.bib) one.
• Similarly, use symbolic abbreviated month names, rather than they full name equivalents. For instance, write

  	month = dec,
    

  instead of

  	month = "December",
    

  Again, this allows the style file to abbreviate month names only if required.
• Remove unneeded curly braces or quotes from integer numbers. For instance, write

  	volume = 33,
  	number = 6,
  	year = 1990,
    

  instead of

  	volume = {33},
  	number = {6},
  	year = {1990},
    

  This is only a matter of style.
• Remove the resolver URL from the Digital Object Identifier (DOI). For instance, write

  	doi = {10.1145/78973.78974},
    

  instead of

  	doi = {http://doi.acm.org/10.1145/78973.78974},
    

  The resolver is not part of the DOI, and should not appear in it.

Examples

• Egon Balas and Manfred W. Padberg. Set partitioning --- a survey. In Nicos Christofides, editor, Combinatorial Optimization, chapter 7, pages 151-210. Wiley, 1979.

• H. Dobbertin, A. Bosselaers, and B. Preneel. RIPEMD-160: A strengthened version of RIPEMD (ftp://ftp.esat.kuleuven.ac.be/pub/cosic/bosselae/ripemd/ripemd160.ps.gz). In Dieter Gollmann, editor, Fast Software Encryption: Third International Workshop, pages 71-82. Springer-Verlag, Cambridge, UK, February 1996. Lecture Notes in Computer Science 1039.

• John L. Hennessy and David A. Patterson. Computer Architecture: A Quantitative Approach. Morgan Kaufmann Publishers, second edition, 1996.

• Brian W. Kernighan. Why Pascal is not my favorite programming language. Computer Science Technical Report 100, Bell Laboratories, Murray Hill, NJ, USA, July 1981. Available online at http://cm.bell-labs.com/cm/cs/cstr. (Reprinted in Comparing and Assessing Programming Languages Ed. A. Feuer N. Gehani Prentice-Hall 1984).

• David P. Maher. Fault induction attacks, tamper resistance, and hostile reverse engineering in perspective. In Rafael Hirschfeld, editor, Financial Cryptography: First International Conference, FC '97, pages 109-121, Anguilla, British West Indies, February 1997. Springer-Verlag. Lecture Notes in Computer Science 1318.

• Jef Poskanzer et al. NETPBM: Extended portable bitmap toolkit. Available online ftp://ftp.x.org/contrib/utilities/, December 1993. Release 7.

• W. H. Press, B. P. Flannery, S. A. Teukolsky, and W. T. Vetterling. Numerical Recipes in C, pages 343-352. Cambridge University Press, 1988.

• Jesse Reisman. Web site design: Less is more. IT Professional, 1(5):63-64, September/October 1999.

• Brian Cantwell Smith. Procedural Reflection in Programming Languages. PhD thesis, Massachusetts Institute of Technology, January 1982.

• Eugene H. Spafford. The internet worm program: An analysis. Technical Report CSD-TR-823, Purdue University, West Lafayette, IN 47907-2004, November 1988.

• Diomidis Spinellis. An implementation of the Haskell language (http://softlab.icsd.aegean.gr/~dspin/pubs/thesis/MEng/html/haskell.pdf). Master's thesis, Imperial College, London, UK, June 1990.

• Diomidis Spinellis. Programming Paradigms as Object Classes: A Structuring Mechanism for Multiparadigm Programming. PhD thesis, Imperial College of Science, Technology and Medicine, London, UK, February 1994.

• Usenix Association. Very High Level Languages Workshop (VHLL), Santa Fe, Mexico, October 1994. Usenix Association.

• AT&T Bell Laboratories, Murray Hill, New Jersey. UNIX Time-Sharing System, Programmer's Manual, Research Version, February 1985. Eighth Edition.

• Niklaus Wirth. From programming language design to computer construction. Communications of the ACM, 28(2):159-164, February 1985.

Tools and Links

References

• John Grossman, editor. The Chicago Manual of Style. The University of Chicago Press, Chicago and London, fourteenth edition, 1993.

• Donald E. Knuth. The TeXbook. Addisson-Wesley, 1989.

• Leslie Lamport. LATEX: A Document Preparation System. Addisson-Wesley, 1985.

• Bernice Sacks Lipkin. Latex for Linux: A Vade Mecum. Springer Verlag, 1999.

• Oren Patashnik. Designing BibTeX styles. Available from the TeX archives, February 1988.

• Norbert Schwarz. Introduction to TeX. Addison-Wesley, 1989.

• Charles H. Sides. How to Write and Present Technical Information. Cambridge University Press, 1991.

Preparing a Poster Presentation

How to Setup a Brilliant Poster Stand

• A visually striking poster
• A physical object related to the work (physical demo, mascot)
• An auto-running presentation or demo running on a PC
• A leaflet to take away
• Related publications (papers, book)
• A knowledgeable presenter interested on the topic

Drafting the Poster Advice

• Print your poster on A0 paper (smaller only if the organizers specify it)
• Prefer a mat to a glossy surface
• Avoid extended text runs
• Use large (sans-serif) fonts
• Liberally use graphical elements
  • Clipart
  • Pictures
  • Diagrams
  • Graphs
  • Rotated text
• Markup the poster areas using large color expanses
• Try to come up with an original and interesting layout
• Make the graphics of the poster tell a story, using elements such as arrows and pictures
• Consider providing a mechanism for obtaining feedback
• Include the contributor's names and contact information (including web site)
• Don't forget to mention your sponsor (if any)

Poster Examples: Good Use of Color

(EURO XX 2004)

(EURO XX 2004)

(MSAD 2004)

Poster Examples: Liberal Use of Graphical Elements

(EURO XX 2004)

(EURO XX 2004)

(MSAD 2004)

(ICSE 2006)

(ICSE 2008)

Poster Examples: Graphics that Tell a Story

(EURO XX 2004)

(EURO XX 2004)

(EURO XX 2004)

Poster Examples: Interesting Layout

The layout is self-referential. The work describes the use of Voronoi diagrams (http://en.wikipedia.org/wiki/Voronoi_diagram) for vote districting, and the poster layout follows the same scheme. This poster won the conference's best poster award. (EURO XX 2004)

(MSAD 2004)

This slide (although a bit crowded) uses numbering and nested layouts to guide the reading order. (ICSE 2006)

Poster Examples: Adding Hardware

The slide includes a folder with a copies of it, and an area for adding comments. (ICSE 2006)

Another approach for collecting comments: a notepad and a pen hanging on a pin (ICSE 2006)

This slide has copies and business cards attached to a paper fastener. (ICSE 2006)

This slide includes a blank area where a projector shows a demo of the software. (ICSE 2008)

Poster Examples: Making do Without a Big Format Printer

This poster is assembled mainly from printed A4 sheets, placed in an interesting pattern. (SPLASH 2012)

This poster is written by hand on flip-chart and A4 sheets. The placement of the A4 sheets is used to indicate how they relate to the larger flip-chart sheets. (SPLASH 2012)

Poster Counterexamples

The paper's pages printed on an A0 sheet

The paper typeset and printed on an A0 sheet; this is worse the previous example, because our eye can't follow printed lines spanning half a metre.

Too much and small text, not enough color (EURO XX 2004)

Too much information (text and small diagrams), glossy paper (EURO XX 2004)

Too much and small text (EURO XX 2004)

Stand Examples

The perfect setup: poster, book, physical demo, laptop, presentation. The board allows the demonstration of Voronoi diagrams (http://en.wikipedia.org/wiki/Voronoi_diagram) using nails and rubber bands. This poster won the conference's best poster award. (EURO XX)

A live hardware demo (MSAD 2004)

Closeup of the live hardware demo (MSAD 2004)

The perfect packing for the demo (MSAD 2004)

Packing List

• The poster (protected in a sturdy cylindrical container). Seal the container's covers with adhesive tape, because they can fall off in the airport handling.
• Double-sided adhesive tape and scissors, pins, or Blue-tack^TM
• The physical object, suitably protected
• Business cards with up to date contact information
• Promotional leaflet
• A laptop for running the demo
• The demo on backup media (CD-ROM, USB stick)
• Publications to distribute (e.g. paper reprints)
• Publications to display (e.g. a book)
• Giveaways: posters, pens, buttons, candy, CDs, T-shirts
• An attire appropriate for the occasion - consider wearing a T-shirt with the research project's logo
• Drinking water
• Reading material, to pass your time if attendance is low

PhD Student and Supervisor Resources

A Reading List for PhD Students (and their Supervisors)

• Phil Agre. Networking on the network: A guide to professional skills for PhD students. Available online http://dlis.gseis.ucla.edu/people/pagre/network.html (http://dlis.gseis.ucla.edu/people/pagre/network.html). Current January 2003, August 2002.

• Steven Alter and Alan R. Dennis. Selecting research topics: Personal experiences and speculations for the future. Communications of the Association for Information Systems, 8:314–329, 2002.

• Vance W. Berger and John P. A. Ioannidis. The Decameron of poor research. British Medical Journal, 329(7480):1436–1440, December 2004. (doi:10.1136/bmj.329.7480.1436 (http://dx.doi.org/10.1136/bmj.329.7480.1436))

• John W. Chinneck. How to organize your thesis. Available online http://www.sce.carleton.ca/faculty/chinneck/thesis.html (http://www.sce.carleton.ca/faculty/chinneck/thesis.html). Current November 2005.

• Claire Kehrwald Cook. Line by Line. Houghton Mifflin, Boston, MA, 1986.

• Gordon B. Davis. Advising and supervising doctoral students: Lessons I have learned. MISRC Working Paper 04-12, University of Minnesota. MIS Research Center, May 2004. Forthcoming as chapter in PhD Supervisors and Student Handbook for Information Systems Research, Butterworth-Heinnemann, 2004.

• Robert A. Day. How to write a scientific paper. IEEE Transactions on Professional Communication, PC-20(1):32–37, June 1977.

• A.R. Dennis and J.S. Valacich. Conducting research in information systems. Communications of AIS, 7(5), 2001. (doi:10.17705/1CAIS.00705 (http://dx.doi.org/10.17705/1CAIS.00705))

• R. Farrow, F. Iniesto, M. Weller, and R. Pitt. The GO-GN Research Methods Handbook. Open Education Research Hub. The Open University, Buckingham, UK, 2020.

• Hugh Gallagher. An exemplary college application essay. Available online http://www.ifs.tuwien.ac.at/ silvia/research-tips/ (http://www.ifs.tuwien.ac.at/~silvia/research-tips/). Current November 2005, 1990.

• William Germano. The scholarly lecture: How to stand and deliver. The Chronicle Review, 50(14), November 2003.

• George D. Gopen and Judith A. Swan. The science of scientific writing. American Scientist, 78(6):550–558, November 1990. Available online https://www.americanscientist.org/blog/the-long-view/the-science-of-scientific-writing (https://www.americanscientist.org/blog/the-long-view/the-science-of-scientific-writing).

• Patricia Gosling and Bart Noordam. Mastering your PhD : Survival and Success in the Doctoral Years and Beyond. Springer, New York, 2006.

• John Grimond. The Economist style guide. Also available online http://www.economist.com/research/StyleGuide/ (http://www.economist.com/research/StyleGuide/)., 2005.

• John Grossman, editor. The Chicago Manual of Style. The University of Chicago Press, Chicago and London, fourteenth edition, 1993.

• Philip Guo. The Ph.D. grind (http://pgbovine.net/PhD-memoir.htm). Available online http://pgbovine.net/PhD-memoir.htm (http://pgbovine.net/PhD-memoir.htm). Current January 2020, 2012.

• Richard W. Hamming. You and your research. Available online via a Google search, March 1986. Bell Communications Research Colloquium Seminar.

• A. R. Hevner, S. T. March, J. Park, and S. Ram. Design science in information systems research. MIS Quarterly, 28(1):75–105, 2004.

• Ralph E. Johnson, Kent Beck, Grady Booch, William Cook, Richard Gabriel, and Rebecca Wirfs-Brock. How to get a paper accepted at OOPSLA (panel). In Proceedings of the Eighth Annual Conference on Object-Oriented Programming Systems, Languages, and Applications, OOPSLA ’93, page 429–436, New York, NY, USA, 1993. Association for Computing Machinery. (doi:10.1145/165854.165934 (http://dx.doi.org/10.1145/165854.165934))

• Simon L. Peyton Jones, John Hughes, and John Launchbury. How to give a great research talk. Available online http://www.ifs.tuwien.ac.at/ silvia/research-tips/Giving%20a%20talk.pdf (http://www.ifs.tuwien.ac.at/~silvia/research-tips/Giving%20a%20talk.pdf). Current November 2005.

• Simon L. Peyton Jones, John Hughes, and John Launchbury. How to write a great research paper. Available online http://www.ifs.tuwien.ac.at/ silvia/research-tips/Writing%20a%20paper.pdf (http://www.ifs.tuwien.ac.at/~silvia/research-tips/Writing%20a%20paper.pdf). Current November 2005.

• Aviel William Strunk Jr. and E. B. White. The Elements of Style. Macmillan Publishing Co., New York, 1979.

• S. Katzoff. Clarity in technical reporting. Technical Report NASA SP-7010, NASA, Washington, D.C., 1964. Second edition. Available online http://techreports.larc.nasa.gov/ltrs/PDF/NASA-64-sp7010.pdf (http://techreports.larc.nasa.gov/ltrs/PDF/NASA-64-sp7010.pdf).

• Barbara Kitchenham and Stuart Charters. Guidelines for performing systematic literature reviews in software engineering. Technical Report EBSE-2007-01, School of Computer Science and Mathematics, Keele University, 2007.

• Barbara A. Kitchenham and Shari L. Pfleeger. Personal opinion surveys. In Forrest Shull, Janice Singer, and Dag I. K. Sjøberg, editors, Guide to Advanced Empirical Software Engineering, pages 63–92. Springer London, London, 2008. (doi:10.1007/978-1-84800-044-5_3 (http://dx.doi.org/10.1007/978-1-84800-044-5_3))

• Donald E. Knuth, Tracy Larrabee, and Paul M. Roberts. Mathematical writing. Available online http://jmlr.csail.mit.edu/reviewing-papers/knuth_mathematical_writing.pdf (http://jmlr.csail.mit.edu/reviewing-papers/knuth_mathematical_writing.pdf). Current January 2020, 1987.

• Markus G. Kuhn. Effective scientific electronic publishing. Available online http://www.cl.cam.ac.uk/ mgk25/publ-tips/ (http://www.cl.cam.ac.uk/~mgk25/publ-tips/). Current March 2008, 2006.

• James Lavin. Proving almost anything: a beginner's guide to a world with infinite solutions. IEEE Potentials, pages 6–7, February/March 1996.

• Adrian Lee, Carina Dennis, and Philip Campbell. Nature's guide for mentors. Nature, 447(7119):791–797, June 2007.

• Ralp Lengler and Marin J. Eppler. A periodic table of visualization methods. Available online http://www.visual-literacy.org/periodic_table/periodic_table.html (http://www.visual-literacy.org/periodic_table/periodic_table.html). Current September 2012.

• Roy Levin and David D. Redell. An evaluation of the ninth SOSP submissions -or- how (and how not) to write a good systems paper. Operating Systems Review, 17(3):35–40, July 1983.

• Jack Lynch. Guide to grammar and style. Available online http://andromeda.rutgers.edu/ jlynch/Writing/index.html (http://andromeda.rutgers.edu/~jlynch/Writing/index.html). Current September 2010.

• Marie desJardins. How to be a good graduate student / advisor. Available online http://www.cs.indiana.edu/how.2b/how.2b.html (http://www.cs.indiana.edu/how.2b/how.2b.html). Current November 2005.

• Marie desJardins. How to succeed in postgraduate study. Available online http://aerg.canberra.edu.au/jardins/t.htm (http://aerg.canberra.edu.au/jardins/t.htm). Current November 2005.

• Matthew Might. Reading for graduate students. Available online http://matt.might.net/articles/books-papers-materials-for-graduate-students/ (http://matt.might.net/articles/books-papers-materials-for-graduate-students/). Current August 2010.

• Matthew Might. Reading for graduate students. Available online http://matt.might.net/articles/ways-to-fail-a-phd/ (http://matt.might.net/articles/ways-to-fail-a-phd/). Current January 2012.

• Silvia Miksch. How to do research. Available online http://www.ifs.tuwien.ac.at/ silvia/research-tips/ (http://www.ifs.tuwien.ac.at/~silvia/research-tips/). Current November 2005, 2005.

• John Mingers. The long and winding road: Getting papers published in top journals. Communications of the Association for Information Systems, 8:330–339, 2002.

• George Orwell. Politics and the english language. Horizon, April 1946. Also available online https://www.orwellfoundation.com/the-orwell-foundation/orwell/essays-and-other-works/politics-and-the-english-language/ (https://www.orwellfoundation.com/the-orwell-foundation/orwell/essays-and-other-works/politics-and-the-english-language/).

• Ian Parberry. A guide for new referees in theoretical computer science. Information and Computation, 112(1):96–116, July 1994. (doi:10.1006/inco.1994.1053 (http://dx.doi.org/10.1006/inco.1994.1053))

• David A. Patterson. How to have a bad career in research/academia. Available online http://www.cs.utah.edu/ lepreau/osdi94/keynote/abstract.html (http://www.cs.utah.edu/~lepreau/osdi94/keynote/abstract.html) and http://www.cs.berkeley.edu/ pattrsn/talks/BadCareer.pdf (http://www.cs.berkeley.edu/~pattrsn/talks/BadCareer.pdf). Current November 2005, November 1994. Invited Talk. First Symposium on Operating Systems Design and Implementation (OSDI '94) keynote address, November 14-17, 1994 Monterey, CA.

• Randy Pausch. Really achieving your childhood dreams. Video available online http://www.youtube.com/watch?v=ji5_MqicxSo (http://www.youtube.com/watch?v=ji5_MqicxSo). Current September 2008, September 2007.

• Vern Paxson. Strategies for sound internet measurement. In Proceedings of the Internet Measurement Conference, Taormina, Sicily, Italy, October 2004.

• Chad Perry. A structured approach to presenting PhD theses: Notes for candidates and their supervisors. In ANZ Doctoral Consortium. University of Sydney, February 1994.

• Estelle M. Phillips and Derek S. Pugh. How to Get a PhD. Open University Press, Buckingham, UK, third edition, 2000.

• Frantz Rowe. What literature review is not: diversity, boundaries and recommendations. European Journal of Information Systems, 23(3):241–255, 2014. (doi:10.1057/ejis.2014.7 (http://dx.doi.org/10.1057/ejis.2014.7))

• E. Robert Schulman and C. Virginia Cox. How to write a Ph.D. dissertation. Annals of Improbable Research, 3(5):8, September 1997.

• E. Robert Schulman. How to write a scientific paper. Annals of Improbable Research, 2(5):8, September 1996.

• Claude Shannon. Creative thinking. Available online https://medium.com/the-mission/a-genius-explains-how-to-be-creative-claude-shannons-long-lost-1952-speech-fbbcb2ebe07f (https://medium.com/the-mission/a-genius-explains-how-to-be-creative-claude-shannons-long-lost-1952-speech-fbbcb2ebe07f). Current August 2017, March 1952.

• Zur Shapira. "i've got a theory paper—do you?": Conceptual, empirical, and theoretical contributions to knowledge in the organizational sciences. Organization Science, 22(5):1312–1321, 2011.

• Mary Shaw. Writing good software engineering research papers. In Proceedings of the 25th International Conference on Software Engineering, pages 726–726. IEEE Computer Society, May 2003.

• Jonathan Shewchuk. Three sins of authors in computer science and math. Available online http://www-2.cs.cmu.edu/ jrs/sins.html.gseis.ucla.edu/people/pagre/network.html (http://www-2.cs.cmu.edu/~jrs/sins.html.gseis.ucla.edu/people/pagre/network.html). Current December 2004, 1997.

• Michael Shortland and Jane Gregory. Communicating Science: A Handbook. Longman Scientific & Technical, 1991.

• Forrest Shull, Janice Singer, and Dag I. K. Sjøberg, editors. Guide to Advanced Empirical Software Engineering. Springer London, London, 2008. (doi:10.1007/978-1-84800-044-5 (http://dx.doi.org/10.1007/978-1-84800-044-5))

• Charles H. Sides. How to Write and Present Technical Information. Cambridge University Press, Cambridge, 1991.

• Yannis Smaragdakis. Phd rants and raves. Available online http://www.cs.uoregon.edu/ yannis/phd-slides.pdf (http://www.cs.uoregon.edu/~yannis/phd-slides.pdf). Current January 2008.

• Alan Jay Smith. The task of the referee. Computer, 23(4):65–71, 1990. (doi:10.1109/2.55470 (http://dx.doi.org/10.1109/2.55470))

• Diomidis Spinellis. The Elements of Computing Style: 180+ Tips for Busy Knowledge Workers. Leanpub, Vancouver, BC, Canada, 2014.

• Diomidis Spinellis. Advice for writing LaTeX documents. Available online https://github.com/dspinellis/latex-advice (https://github.com/dspinellis/latex-advice). Current January 2019, January 2019.

• William H. Starbuck. Fussy professor Starbuck's cookbook of handy-dandy prescriptions for ambitious academic authors or why I hate passive verbs and love my word processor. Available online http://pages.stern.nyu.edu/ wstarbuc/Writing/Fussy.htm (http://pages.stern.nyu.edu/~wstarbuc/Writing/Fussy.htm). Current May 2005, 1999.

• Klaas-Jan Stol and Brian Fitzgerald. The ABC of software engineering research. ACM Trans. Softw. Eng. Methodol., 27(3):11:1–11:51, September 2018. (doi:10.1145/3241743 (http://dx.doi.org/10.1145/3241743))

• John O. Summers. Guidelines for conducting research and publishing in marketing: From conceptualization through the review process. Journal of the Academy of Marketing Science, 29(4):404–415, 2001. (doi:10.1177/03079450094243 (http://dx.doi.org/10.1177/03079450094243))

• Ivan Sutherland. Technology and courage. Sun Labs Perspectives Essay Series 96-1, Sun Microsystems Laboratories, Santa Clara, CA, April 1996. Available online http://research.sun.com/techrep/Perspectives/smli_ps-1.pdf (http://research.sun.com/techrep/Perspectives/smli_ps-1.pdf).

• Science jokes. Available online http://www.xs4all.nl/ jcdverha/scijokes/ (http://www.xs4all.nl/~jcdverha/scijokes/). Current February 2007, 2007.

• M. Vidoni. A systematic process for mining software repositories: Results from a systematic literature review. Information and Software Technology, 144:106791, 2022. (doi:10.1016/j.infsof.2021.106791 (http://dx.doi.org/10.1016/j.infsof.2021.106791))

• Toby Walsh. Empirical methods in CS and AI. Available online http://www.cse.unsw.edu.au/ tw/empirical.html (http://www.cse.unsw.edu.au/~tw/empirical.html). Current October 2014.

• Jane Webster and Richard T. Watson. Analyzing the past to prepare for the future: Writing a literature review. MIS Quarterly, 26(2):xiii–xxiii, June 2002.

• Roel Wieringa. Writing a report about design research. Available online http://wwwhome.cs.utwente.nl/ roelw/ReportingAboutDesignResearch.pdf (http://wwwhome.cs.utwente.nl/~roelw/ReportingAboutDesignResearch.pdf). Current September 2008, 2007.

• Gene Woolsey. An exemplary essay on communication or corporate style, corporate substance, & the sting. Interfaces, 9(3):10–12, May 1979.

PhD Student Achievements

26 February 2009

The book Beautiful Architecture: Leading Thinkers Reveal the Hidden Beauty in Software Design (http://oreilly.com/catalog/9780596517984/) (O'Reilly, 2008, ISBN 9780596517984) co-edited by Georgios Gousios obtained the top rank on the amazon.co.uk Software Architecture books category. The book's royalties are donated to the international humanitarian aid organisation Médecins Sans Frontières (http://www.msf.org/).

February 2009

Vassilis Karakoidas is awarded funding for his research through AUEB's Funding Programme for Basic Research (PEVE).

January 2009

Dimitris Mitropoulos publishes a paper in a high-impact journal: SDriver: Location-specific signatures prevent SQL injection attacks. Computers and Security, 2009.

October 13th, 2008

Vasileios Vlachos is elected Lecturer in the Department of Computer Science and Telecommunications at the Technological Educational Institution of Larissa. The subject of his post is the Development and Security of Internet Applications.

September 2008

Vasileios Vlachos publishes a paper he co-autored during his PhD study in a top-impact journal: Power laws in software. ACM Transactions on Software Engineering and Methodology, 18(1):1–26, September 2008. Article 2.

June 2008

The paper A PRoactive Malware Identification System based on the Computer Hygiene Principles (Information Management and Computer Security, 15(4):295-312, 2007) co-authored by Vasileios Vlachos was awarded (http://info.emeraldinsight.com/authors/literati/awards.htm?jr=imcs) by Emerald (http://www.emeraldinsight.com/) publishers with the "Highly Commended Paper" distinction. The award was given by the journal's editorial board to three papers as part of the "Literati Network Awards for Excellence 2008".

May 2008

Vassilis Karakoidas publishes a paper in a high-impact journal: FIRE/J — optimizing regular expression searches with generative programming. Software: Practice & Experience, 38(6):557–573, May 2008.

November 17th, 2007

Konstantinos Chorianopoulos is elected Lecturer in the Department of Informatics at the Ionian University.

July 24th, 2007

Vasileios Vlachos successfully defends his PhD thesis.

April 2006

The paper A survey of peer-to-peer content distribution technologies (ACM Computing Surveys, 36(4):335–371, December 2004) co-authored by Stephanos Androutsellis Theotokis obtained the top yearly download rank in the ACM's digital library popular magazine and computing surveys articles category.

Table from the Communications of the ACM Volume 49, Number 4 (2006), Pages 29-30.

January 2006

Stephanos Androutsellis Theotokis, Georgios Gousios, and Konstantinos Stroggylos are awarded a scholarhip through the framework of the "Reinforcement Programme of Human Research Manpower" (PENED) co-financed by National and Community Funds (25% from the Greek Ministry of Development-General Secretariat of Research and Technology and 75% from E.U.-European Social Fund).

December 2004

Stephanos Androutsellis Theotokis publishes a paper in a top-impact journal: A survey of peer-to-peer content distribution technologies. ACM Computing Surveys, 36(4):335–371, December 2004.

July 2004

Vasileios Vlachos is awarded a scholarship co-funded by the European Social Fund and National Resources - EPEAEK II - IRAKLITOS Fellowships for research of Athens University of Economics and Business.

June 2004

Vasileios Vlachos and Stefanos Androutsellis Theotokis publish a paper in a high-impact journal: Security applications of peer-to-peer networks. Computer Networks, 45(2):195–205, June 2004.

May 10th, 2004

Konstantinos Chorianopoulos successfully defends his PhD thesis.

May 2004

Konstantinos Chorianopoulos publishes a paper in a high-impact journal: User interface development for interactive television: Extending a commercial DTV platform to the virtual channel API. Computers & Graphics, 28(2):157–166, April 2004.

April 2004

Vasileios Vlachos coordinated the student team that won the third place in the national phase of the Microsoft Imagine Cup 2004 competition.

December 2004

The paper A survey of peer-to-peer content distribution technologies (ACM Computing Surveys, 36(4):335–371, December 2004) co-authored by Stephanos Androutsellis Theotokis obtained the top monthly download rank in the ACM's digital library popular magazine and computing surveys articles category.

Table from the Communications of the ACM Volume 48, Number 9 (2005), Pages 29-30.

June 16th, 2002

Konstantinos Raptis successfully defends his PhD thesis.

June 2000

Konstantinos Raptis publishes a paper in a high-impact journal: Component mining: A process and its pattern language. Information and Software Technology, 42(9):609–617, June 2000.

The PhD Game

The Nine Types of Principal Investigators

From The NIH Catalyst, Volume 3, page 23.

Delaying Higher Degree Completion

Collated by Diana Bental (D.Bental@lancaster.ac.uk) with the help of contributions from many PhD students, past and present.

Purpose

This document is intended for supervisors of students registered for higher degrees in just about any University department anywhere.

Though the presentation of the document is deliberately light in tone, the contents are based on a collation of feedback from a fairly large number of students currently pursuing their studies for a Ph.D.

Acknowledgement

This document is extremely close to that published in the AISB Quarterly (No. 80, Summer 1992), the quarterly magazine of the Society for the Study of Artificial Intelligence and the Simulation of Behaviour. It has been slightly edited by Paul Brna.

``All the information here has in fact been contributed by PhD students, past and present. Much of what is written here has been exaggerated for effect, but it is all based on students' real experiences and some of it is no more than a literal description of what has happened to them.'' (page 60, AISBQ No 80, Summer 1992)

Many PhD students have collaborated to provide the insights that are found within. Our thanks go to them, and to those that helped in pulling the contributions together into such a formidable body of knowledge.

Thesis Prevention: Advice to Supervisors

Clearly, it is not easy to prevent reasonably intelligent and mildly motivated students (such as ourselves) from producing useful work. Nevertheless, he has developed some excellent techniques for Thesis Prevention which we feel may be of use to others, and which we, Professor Hacker's research students present here for your enlightenment and entertainment. If you, as a supervisor, wish to prevent your students from researching and writing up a thesis, or indeed doing anything useful at all, we hope you will take inspiration from Prof. Hacker's example.

On Arrival: Settling In

Try to be away when the student arrives. Out of the country is preferable, but in today's economic climate Prof. Hacker acknowledges that it is also acceptable to be merely in another city. In this case, your student cannot try to set up any kind of regular contact with you, and will be forced to become independent of you early on.

Supervisions

Initially, Prof. Hacker attempted to shelve the whole problem of supervisions by simply refusing to see his students at all. He would smile at them on his way out of the tea room, realising that this was as much supervision as any student could expect, especially if he occasionally discussed the weather with them when meeting in the corridor. He was forced to drop this approach when his department laid down some guidelines which insisted that supervisors should actually sit down in the same room as students every few weeks and discuss the students' work. This was only a temporary setback to the intrepid Prof. Hacker, of the sort that spurs a good researcher on to new heights. It was at this point that he made some stunning discoveries about how to use these meetings to achieve depths of demotivation previously beyond human imagining.

Basic Etiquette

Here are some guidelines which, if adhered to strictly for even quite a short time, will convey the desired message to the student: a student's work is unimportant, uninteresting and not worth anybody's time, not even their supervisor's.

Arrive late for all appointments with the student. If you can't manage that, then be occupied in some long and complicated task when the student arrives and be sure to finish the task before turning your attention to the student.

Encourage interruptions. Do not cut callers short with the rude statement that you are in a meeting. Never re-route telephone calls. Ask the secretaries to route all their calls through your office as a return favour for all those times you've re-routed your calls. Encourage your head of department, researchers from overseas and your three-year-old child to call at these times. Make any outgoing calls that you suddenly realise are necessary.

If supervisions are held in your office (and they needn't be) make sure that you have a keyboard handy. This is so that you can, in the middle of any detailed explanations that your student may indulge in, reach for the keyboard and read your mail. Prof. Hacker likes to get his workstation to emit distracting beeps at random intervals.

Cancel meetings frequently on the flimsiest pretexts that you can. Do not ever tell students that the meeting is cancelled, but let them come prepared for a supervision and find the room empty. (If the students have prepared for the supervision, that is 90 per cent of the benefit anyway, so don't feel that you are depriving them.)

The Group Supervision

Try as far as possible to conduct the supervision of several students simultaneously. The students can talk to each other, thus decreasing your need to contribute. If they are all working on unrelated projects and share no common terminology, their attempts to hold a useful discussion should provide you with much diversion.

Productivity is increased even further if this is done as a lunch-time exercise. After all, you have to eat sometime, and if you can do this and fulfill your obligations to your students at the same time, so much the better.

Prof. Hacker warns that only experienced supervisors should attempt simultaneous supervision of more than two students. Note also that fewer than two is really not cost effective and in this case you should try to turn up as late as possible, grab your lunch and be busy eating for most of the next 15 minutes (which is the recommended duration for such supervisions).

Preparing for Supervisions

Do not prepare for any supervision. If you have an excellent memory, know all the background to the student's project and see the student often, then this technique will not help you. But if not, then your failure to take note of what the student has been doing and/or your failure to look back over your notes will enable you to start each supervision from scratch, requiring the student to explain and justify every step of background to their work before they can discuss any real problems with you. Do this one well enough and you will never have to discuss any real technical problems with your student.

Content of Supervisions

You will find that you are expected to talk during supervisions. Prof. Hacker prefers to avoid the strain of listening critically to students' ideas, and still more to avoid the strain of thinking up helpful and detailed advice.

Avoid at all times any discussion of practical possibilities. Inspire the student by using supervision meetings to soliloquise on all your vaguest and most esoteric ideas, particularly on philosophical issues. Tell lengthy anecdotes to illustrate a point which the student will have forgotten by the time you finish.

Your students will also expect you to respond to their ideas. Prof. Hacker has demonstrated that three quite different techniques may be expected to produce the same effect.

1. Always agree with any suggestions a student makes. At first, this will boost their confidence beyond their wildest expectations which means they won't come back for supervision for a long time. The next time you use this approach they will become suspicious that whatever they say is enthusiastically accepted, however ludicrous, so they won't come for supervision since they don't trust you.

2. Always disagree with what the student says. This is more dangerous since it is confrontational and so should only be attempted by persons of large stature or with a black belt in an appropriate martial art. A good way of ridding yourself of students with the possibility of unlimited earnings from suing for assault. If you have been unable to prevent a student from progressing deeply into a thesis, you can discourage the student by commenting only on the weak aspects of the work and assuming that the student will know, perhaps by psychic projection, that you think the rest is good.

3. Maintain a strict neutrality to avoid unfairly influencing the student. This is far less obvious than either of the two previous approaches and it still frees you from having to think about what the student is doing. Never give clear approval or disapproval of any ideas the student comes up with, so that they don't know if the idea should be followed up or abandoned. The student, unlike you, is unfamiliar with doing a Higher Degree, so it would be unfair to bias their ideas of what is appropriate.

Research Guidance

Directing the Area and Scope of your Students' Research

A good way to prevent your students from doing any useful research is to ensure that they choose the right topic. An ideal topic is one that the student isn't interested in, and that the supervisor knows nothing about. Prof. Hacker is especially pleased with a topic if the department lacks the facilities required to pursue it, and if any results are likely to be inconclusive.

The department accidentally played right into Prof. Hacker's hands when it instigated the requirement that students submit a thesis proposal at the end of their first year. A feebler supervisor would have given in and tried to ensure that students produce a detailed and well thought out proposal by this deadline. Prof. Hacker is made of sterner stuff. By following techniques given in this section and the reading techniques given in the section below throughout his students' first year, Prof. Hacker was able to use this deadline to panic his students into choosing the right sort of topic - for his purposes.

Discourage students from following up their initial interests. Post-graduate work is a chance to explore new areas! Suggest subject areas that they know nothing about, so that they spend a year or two trying to understand an area before they find out that it's not worth the trouble to pursue.

Suggest that the student should apply a promising technique to a useless area, such as applying termination proof theory to Cobol programs.

Suggest that students should research a `related' area to their current research since the two areas share a common word in their titles, even though they are lightyears apart (see the following section on reading). This could set them on the wrong track for years.

Wait a year or two and then find a good reason why it would be pointless for the student to continue their current line of research. Refer them to the paper that reports someone else having done the work they intend to do, or explain that the equipment or facilities that the project depends upon will be unavailable. Remember that just because you know that a research group of thirty staff is working on a topic that your student is investigating alone, or that your equipment bid is unlikely to be funded, you don't have to tell the student immediately. You wouldn't want to discourage them, after all.

Finally, gild the lily. Prof. Hacker is delighted to report that having been initially sceptical about a student's choice of project and having suggested that the student spend several months preparing some alternative proposals, he was able to inform the student that the student's original proposal was indeed the best.

Directing the Student's Reading

Guidance on reading is vital. Prof. Hacker's aim is to ensure that his students' reading lists increase in length exponentially.

If ever a student raises an interesting point that Prof. Hacker fears might lead to a technical discussion, he exclaims ``Ah yes, you really must read what Whizzbang and Genius have to say about that in their theses at the University of Obscurity, Darkest Peru in about, oh, 1965''. He makes it quite clear that there is no point discussing the topic further until the student has read the vital reference (or better still, five or six of them).

The choice of reference material should be guided by a generate and test procedure. Prof. Hacker generates appropriate reference material by looking for titles that share a common word with the student's topic regardless of context. He filters out inappropriate references by making sure that all the references he gives are very hard to dig out. (Never actually produce one to lend to your students, for students are independent researchers who must not be spoon-fed.) Prof. Hacker prefers to mention theses done in remote corners of the world and of 1960s or 70's vintage.

The consistent application of these guidelines should put the student into a sufficiently desperate state that they will settle on a completely inappropriate topic when they have to write their thesis proposal (as discussed in the previous section).

Writing Up

If your students get this far (and if you follow all our guidelines strictly, we trust that your students will not), you will need to assist your students and ensure that they never finish writing up. Prof. Hacker takes care to identify every concept referred to in his students' work and reminds students that there must be a background chapter on each concept in the thesis, with accompanying related work section. As the size of this grows (we suspect factorially, see our appendix on complexity theory) that is a very off-putting task. If a student actually attempts the task it is guaranteed to produce a nervous breakdown, as each of these background chapters then requires further elaboration in itself, and so on recursively.

Reading

Students will expect that you will read technical papers that they have written, however badly worded, boring and pointless they may be. There are two main approaches to preventing students from giving you things to read. Applied with sufficient vigour they may prevent your student from ever writing anything at all.

1. Do not write comments on anything that the student has written. This conveys the impression that you have not read the paper without providing the student with any concrete evidence that could be used against you. You can make verbal comments. These give the impression that yes, you did read the paper but you found it too pointless to be worth searching for a pencil. If you wish to convey the impression that you read the paper with pencil in hand and thought nothing of the contents, you can simply dip into the middle of the paper and correct a minor grammatical error.

2. Allow several months to elapse before reading (or claiming to have read) anything the student writes. This is risky with drafts of conference papers which may have a deadline for submission, but is an adequate way to deal with thesis chapters, thesis proposals and other half-baked nonsense. This method is especially useful when applied to something that you have asked the student to write.

Prof. Hacker occasionally takes a more subtle approach, in which comments are always written but are content free or (better still) ambiguous, thus leaving the student with the work of incorporating the wrong ideas into their paper.

If Prof. Hacker makes any comments on style or content, e.g. that some sentence should be re-written in a particular way, Prof. Hacker tries to remember to reverse the comments in the next draft. This can be applied ad infinitum, or at least until he forgets to do it.

Publications

Prof. Hacker believes that it is an excellent idea for a supervisor to add his or her name to all of a student's published work. This is justified for two reasons. Firstly, you are doing the student a favour because you are a more famous researcher and therefore your name as co-author will mean that the paper is more likely to be accepted. Secondly, you are the student's supervisor and therefore you are naturally the inspiration for everything the student publishes. This will delight the student even further if you have been practising all the other the techniques proposed here, especially those suggested in the section on reading.

Extra-Mural Activities

All supervisors should encourage their students to make contacts in other institutions and to broaden their range of interests. The ideal way to do this is to ask students to organise a conference or workshop, preferably on a topic unrelated to their thesis work.

Conclusions

We believe that we have gathered together a collection of techniques that will be of widespread use in the slowing down and prevention of the production of theses for Higher Degrees. We have emphasised the many ways in which a supervisor can contribute, and the great variety of approaches to the prevention of theses. Finally, we would like to think that Professor Hacker's supervision techniques were unique to him but we fear that they are not.

A Letter Regarding Attendance Time

And, yes, the receipient was a former student (http://www.carreira.ethz.ch/people/former_members).

(From the web page of Jinghai Rao (http://www.cs.cmu.edu/~jinghai/), brought to my attention by Vassilis Prevelakis (http://vp.cs.drexel.edu/).)

189 Things (Not) to Do at or for your Thesis Defense (in no particular order)

1. "Ladies and Gentlemen, please rise for the singing of our National Anthem..."
2. Charge 25 cents a cup for coffee.
3. "Charge the mound" when a professor beans you with a high fast question.
4. Interpretive dance.
5. "Musical accompaniment provided by..."
6. Stage your own death/suicide.
7. Lead the specators in a Wave.
8. Have a sing-a-long.
9. "You call THAT a question? How the hell did they make you a professor?"
10. "Ladies and Gentlemen, as I dim the lights, please hold hands and concentrate so that we may channel the spirit of Lord Kelvin..."
11. Have bodyguards outside the room to "discourage" certain professors from sitting in.
12. Puppet show.
13. Group prayer.
14. Animal sacrifice to the god of the Underworld.
15. Sell T-shirts to recoup the cost of copying, binding, etc.
16. "I'm sorry, I can't hear you - there's a banana in my ear!"
17. Imitate Groucho Marx.
18. Mime.
19. Hold a Tupperware party.
20. Have a bikini-clad model be in charge of changing the overheads.
21. "Everybody rhumba!!"
22. "And it would have worked if it weren't for those meddling kids..."
23. Charge a cover and check for ID.
24. "In protest of our government's systematic and brutal oppression of minorities..."
25. "Anybody else as drunk as I am?"
26. Smoke machines, dramatic lighting, pyrotechnics...
27. Use a Super Soaker to point at people.
28. Surreptitioulsy fill the room with laughing gas.
29. Door prizes and a raffle.
30. "Please phrase your question in the form of an answer..."
31. "And now, a word from our sponsor..."
32. Present your entire talk in iambic pentameter.
33. Whine piteously, beg, cry...
34. Switch halfway through your talk to Pig Latin. Or Finnish Pig Latin.
35. The Emperor's New Slides ("only fools can't see the writing...")
36. Table dance (you or an exotic dancer).
37. Fashion show.
38. "Yo, a smooth shout out to my homies..."
39. "I'd like to thank the Academy..."
40. Minstrel show (blackface, etc.).
41. Previews, cartoons, and the Jimmy Fund.
42. Pass the collection basket.
43. Two-drink minimum.
44. Black tie only.
45. "Which reminds me of a story - A Black guy, a Chinese guy, and a Jew walked into a bar..."
46. Incite a revolt.
47. Hire the Goodyear Blimp to circle the building.
48. Release a flock of doves.
49. Defense by proxy.
50. "And now a reading from the Book of Mormon..."
51. Leave Jehovah's Witness pamphlets scattered about.
52. "There will be a short quiz after my presentation..."
53. "Professor Robinson, will you marry me?"
54. Bring your pet boa.
55. Tell ghost stories.
56. Do a "show and tell".
57. Food fight.
58. Challenge a professor to a duel. Slapping him with a glove is optional.
59. Halftime show.
60. "Duck, duck, duck, duck... GOOSE!"
61. "OK - which one of you farted?"
62. Rimshot.
63. Sell those big foam "We're number #1 (sic)" hands.
64. Pass out souvenier matchbooks.
65. 3-ring defense.
66. "Tag - you're it!"
67. Circulate a vicious rumor that the Dead will be opening, making sure that it gets on the radio stations, and escape during all the commotion.
68. Post signs: "Due to a computer error at the Registrar's Office, the original room is not available, and the defense has been relocated to Made-up non-existent room number)"
69. Hang a pinata over the table and have a strolling mariachi band.
70. Make each professor remove an item of clothing for each question he asks.
71. Rent a billboard on the highway proclaiming "Thanks for passing me Professors X,Y, and Z" - BEFORE your defense happens.
72. Have a make-your-own-sundae table.
73. Make committee members wear silly hats.
74. Simulate your experiment with a virtual reality system for the spectators.
75. Do a soft-shoe routine.
76. Throw a masquerade defense, complete with bobbing for apples and pin-the-tail-on-the-donkey.
77. Use a Greek Chorus to highlight important points.
78. "The responsorial psalm can be found on page 124 of the thesis..."
79. Tap dance.
80. Vaudeville.
81. "I'm sorry Professor Smith, I didn't say 'SIMON SAYS any questions?'. You're out."
82. Flex and show off those massive pecs.
83. Dress in top hat and tails.
84. Hold a pre-defense pep rally, complete with cheerleaders, pep band, and a bonfire.
85. Detonate a small nuclear device in the room. Or threaten to.
86. Shadow puppets.
87. Show slides of your last vacation.
88. Put your overheads on a film strip. Designate a professor to be in charge of turning the strip when the tape recording beeps.
89. Same as #88, but instead of a tape recorder, go around the room making a different person read the pre-written text for each picture.
90. "OK, everybody - heads down on the desk until you show me you can behave."
91. Call your advisor "sweetie".
92. Have everyone pose for a group photo.
93. Instant replay.
94. Laugh maniacally.
95. Talk with your mouth full.
96. Start speaking in tongues.
97. Explode.
98. Implode.
99. Spontaneously combust.
100. Answer every question with a question.
101. Moon everyone in the room after you are done.
102. Rearrange the chairs into a peace symbol.
103. Refer to yourself in the third person, like Julius Caesar did.
104. Mention your professor as "my helper."
105. Say that you'd like to thank a few people. Pull out the White Pages. Start reading.
106. Advertise it as "pot luck".
107. Talk in Klingonese.
108. Dress like your favorite character from "Star Trek".
109. Ask imaginary helpers to change transparencies; fly off the handle when they don't.
110. Wear a trenchcoat. And nothing else.
111. Dress in a Wild West style.
112. Go dressed in scuba gear. Use the oxygen tank.
113. Preface with the story of your life.
114. Wear a swimsuit from the opposite sex: man - wear a bikini, woman - wear trunks.
115. Have bodyguards on your sides as you talk. The bigger, the better. Have a questioner thrown out "as an example."
116. Have someone wheel in a big cake with you in it. Jump out and begin.
117. Perform your defense as a Greek tragedy, kill yourself offstage when you're done.
118. Half way through, break down. Go to your professor, curl up on his or her lap and call him or her "Mommy". Suck your thumb.
119. Suddenly develop Turret's Syndrome.
120. Suddenly develop the China Syndrome.
121. "This defense has been sponsored by the fine people at (your favorite corporation)..."
122. Secede from the U.S. Give yourself political asylum.
123. Talk in Canadianese - add an "eh" after every sentence.
124. When a professor asks you a question, argue with your imaginary twin over the final answer.
125. Videotape it ahead of time, and get someone set it up to show. Come in the back and sit there. When your tape is done, ask for questions. In person.
126. Have every person pick a "CB" handle. Enforce their usage. Talk in CB lingo. End every statement with "good buddy." End every question with "over."
127. Provide party favors. Noisy ones.
128. Frequently ask if anyone has to go to the potty.
129. Mention that you have to hurry because "Hard Copy" is on in 15 minutes.
130. Dress like your school mascot.
131. Urge your committee that if they like your defense enough to tell two friends, and then they'll tell two friends, and so on, and so on...
132. Show up in drag accompanied by the Drag Queens you met at last night's performance and proclaim your thesis presentation will instead discuss: "Blue Eyeshadow: Our Friend Or Foe?" From: smitch#NoSpam.alcor.concordia.ca (Sidney N. Mitchell)
133. Plead the fifth ammendment if you can't answer a question.
134. Keep your back to the committee during the presentation and defense phases.
135. Answer only questions that begin with sir and end with sir. (tell your committe this beforehand).
136. Limit the number of questions that you will allow, and then when the limit is almost reached, go into aerobics terminology... four more...three more...two more..and...rest.
137. Ignore the committee and say "I think that young man/lady at the back has a question".
138. Have your parents call your committee members repeatedly the week before your defense to tell them how expensive it is putting a child through graduate school etc.
139. At the defense, have your parents sit directly behind your committee.
140. Burp, pass gas, scratch (anywhere repeatedly), and pick your nose.
141. "Laugh, will you? Well, they laughed at Galileo, they laughed at Einstein..."
142. Hand out 3-D glasses.
143. "I'm rubber, you're glue..."
144. Go into labor (especially for men).
145. Give your entire speech in a "Marvin Martian" accent.
146. "I don't know - I didn't write this."
147. Before your defense, build trapdoors underneath all the seats.
148. Swing in through the window, yelling a la Tarzan.
149. Lock the department head and his secretary out of the defense room. And the coffee lounge, the department office, the copy room, and the mail room. Heck, lock them out of the building. And refuse to sell them stamps. (NOTE: This is an inside gripe, based on conditions that existed in the ME department at WPI while we were there. Sorry.)
150. Roll credits at the end. Include a "key grip", and a "best boy".
151. Hang a disco ball in the center of the room. John Travolta pose optional.
152. Invite the homeless.
153. "I could answer that, but then I'd have to kill you"
154. Hide.
155. Get a friend to ask the first question. Draw a blank-loaded gun and "shoot" him. Have him make a great scene of dying (fake blood helps). Turn to the stunned audience and ask "any other wise-ass remarks?"
156. Same as #154, except use real bullets.
157. "Well, I saw it on the internet, so I figured it might be a good idea..."
158. Wear clown makeup, a clown wig, clown shoes, and a clown nose. And nothing else.
159. Use the words "marginalized", "empowerment", and "patriarchy".
160. Play Thesis Mad Libs.
161. Try to use normal printed paper on the overhead projector.
162. Do your entire defense operatically.
163. Invite your parents. Especially if they are fond of fawning over you. ("We always knew he was such an intelligent child")
164. Flash "APPLAUSE" and "LAUGHTER" signs.
165. Mosh pit.
166. Have cheerleaders. ("Gimme an 'A'!!")
167. Bring Howard Cosell out of retirement to do color commentary.
168. "I say Hallelujah, brothers and sisters!"
169. Claim political asylum.
170. Traffic reports every 10 minutes on the 1's.
171. Introduce the "Eyewitness Thesis Team". Near the end of your talk, cut to Jim with sports and Alison with the weather.
172. Live radio and TV coverage.
173. Hang a sign that says "Thank you for not asking questions"
174. Bring a microphone. Point it at the questioner, talk-show style.
175. Use a TelePromTer
176. "Take my wife - please!"
177. Refuse to answer questions unless they phrase the question as a limerick.
178. Have everyone bring wine glasses. When they clink the glasses with a spoon, you have to kiss your thesis. Or your advisor.
179. Offer a toast.
180. Firewalk.
181. Start giving your presentation 15 minutes early.
182. Play drinking thesis games. Drink for each overhead. Drink for each question. Chug for each awkward pause. This goes for the audience as well.
183. Swoop in with a cape and tights, Superman style.
184. "By the power of Greyskull..."
185. Use any past or present Saturday Night Live catchphrase. Not.
186. Stand on the table.
187. Sell commercial time for your talk and ad space on your overheads.
188. Hold a raffle.
189. "You think this defense was bad? Let me read this list to show you what I COULD have done..."

(FINAL FINAL NOTE: Circulate this list freely if you'd like, but please remember to credit Peter, Jim, and Alison as the major authors.)

Recommended C Style and Coding Standards

Author List

Introduction

This document is a modified version of a document from a committee formed at AT&T's Indian Hill labs to establish a common set of coding standards and recommendations for the Indian Hill community. The scope of this work is C coding style. Good style should encourage consistent layout, improve portability, and reduce errors. This work does not cover functional organization, or general issues such as the use of gotos. We have tried to combine previous work [1,6,8] on C style into a uniform set of standards that should be appropriate for any project using C, although parts are biased towards particular systems. The opinions in this document do not reflect the opinions of all authors. Please reflect comments and suggestions to the last author. Of necessity, these standards cannot cover all situations. Experience and informed judgement count for much. Programmers who encounter unusual situations should consult either experienced C programmers or code written by experienced C programmers (preferably following these rules).

Ultimately, the goal of these standards is to increase portability, reduce maintenance, and above all improve clarity.

Many of the style choices here are somewhat arbitrary. Mixed coding style is harder to maintain than bad coding style. When changing existing code it is better to conform to the style (indentation, spacing, commenting, naming conventions) of the existing code than it is to blindly follow this document. This is particularly relevant when coding Microsoft Windows programs which depend on the Microsoft style of declarations and coding.

``To be clear is professional; not to be clear is unprofessional.'' - Sir Ernest Gowers.

File Organization

A file consists of various sections that should be separated by several blank lines. Although there is no maximum length limit for source files, files with more than about 1000 lines are cumbersome to deal with. The editor may not have enough temp space to edit the file, compilations will go more slowly, etc. Many rows of asterisks, for example, present little information compared to the time it takes to scroll past, and are discouraged. Lines longer than 79 columns are not handled well by all terminals or windows and should be avoided if possible. Excessively long lines which result from deep indenting are often a symptom of poorly-organized code.

File Naming Conventions

File names are made up of a base name, and an optional period and suffix. The first character of the name should be a letter and all characters (except the period) should be lower-case letters and numbers. The base name should be eight or fewer characters and the suffix should be three or fewer characters (four, if you include the period). These rules apply to both program files and default files used and produced by the program (e.g., ``rogue.sav'').

Some compilers and tools require certain suffix conventions for names of files [5]. The following suffixes are required:

• C source file names must end in .c
• MS-DOS, OS/2 and NT assembler source file names must end in .asm
• Unix assembler source file names must end in .s

The following conventions are universally followed:

• MS-DOS, OS/2 and NT relocatable object file names end in .obj
• Unix relocatable object file names end in .o
• Include header file names end in .h.
• Yacc source file names end in .y
• Lex source file names end in .l

In addition, it is conventional to use ``Makefile'' for the control file for make (for systems that support it) and ``README'' for a summary of the contents of the directory or directory tree.

Program Files

The suggested order of sections for a program file is as follows:

1. First in the file is a prologue that tells what is in that file. A description of the purpose of the objects in the files (whether they be functions, external data declarations or definitions, or something else) is more useful than a list of the object names. The prologue also contains author(s), revision control information, copyright message, references, etc.

   /*
    * bitmap -- Routines that operate on square bitmaps
    *
    * (C) Copyright Yoyodyne Enterprises.  All rights reserved.
    *
    * Author: John Smith
    *
    * $Header$
    *
    */
   

2. Any header file includes should be next. If the include is for a non-obvious reason, the reason should be commented. In most cases, system include files like stdio.h should be included before user include files.
3. Any defines and typedefs that apply to the file as a whole are next. One normal order is to have ``constant'' macros first, then ``function'' macros, then typedefs and enums.
4. Next come the global (external) data declarations, usually in the order: externs, non-static globals, static globals. If a set of defines applies to a particular piece of global data (such as a flags word), the defines should be immediately after the data declaration or embedded in structure declarations, indented to put the defines one level deeper than the first keyword of the declaration to which they apply.
5. The functions come last, and should be in some sort of meaningful order. Like functions should appear together. A ``depth-first'' (functions defined as soon as possible before their calls) is preferred over a ``breadth-first'' approach (functions on a similar level of abstraction together). Considerable judgement is called for here. If defining large numbers of essentially-independent utility functions, consider alphabetical order.

Header Files

Header files are files that are included in other files prior to compilation by the C preprocessor. Some, such as stdio.h, are defined at the system level and must included by any program using the standard I/O library. Header files are also used to contain data declarations and defines that are needed by more than one program. Header files should be functionally organized, i.e., declarations for separate subsystems should be in separate header files. Also, if a set of declarations is likely to change when code is ported from one machine to another, those declarations should be in a separate header file.

Avoid private header filenames that are the same as library header filenames. The statement #include """math.h""" will include the standard library math header file if the intended one is not found in the current directory. If this is what you want to happen, comment this fact. Don't use absolute pathnames for header files. Use the <name> construction for getting them from a standard place, or define them relative to the current directory. The ``include-path'' option of the C compiler (-I on many systems) is the best way to handle extensive private libraries of header files; it permits reorganizing the directory structure without having to alter source files.

Header files that declare functions or external variables should be included in the file that defines the function or variable. That way, the compiler can do type checking and the external declaration will always agree with the definition.

Defining variables in a header file is often a poor idea. Frequently it is a symptom of poor partitioning of code between files. Also, some objects like typedefs and initialized data definitions cannot be seen twice by the compiler in one compilation. On some systems, repeating uninitialized declarations without the extern keyword also causes problems. Repeated declarations can happen if include files are nested and will cause the compilation to fail.

Header files should not be nested. The prologue for a header file should, therefore, describe what other headers need to be #included for the header to be functional. In extreme cases, where a large number of header files are to be included in several different source files, it is acceptable to put all common #includes in one include file.

It is common to put the following into each .h file to prevent accidental double-inclusion.

#ifndef EXAMPLE_H
#define EXAMPLE_H
/* body of example.h file */
/* ...	*/
#endif /* EXAMPLE_H */

This double-inclusion mechanism should not be relied upon, particularly to perform nested includes.

Other Files

It is conventional to have a file called ``README'' to document both ``the bigger picture'' and issues for the program as a whole. For example, it is common to include a list of all conditional compilation flags and what they mean. It is also common to list files that are machine dependent, etc.

Comments

``When the code and the comments disagree, both are probably wrong.'' - Norm Schryer

The comments should describe what is happening, how it is being done, what parameters mean, which globals are used and which are modified, and any restrictions or bugs. Avoid, however, comments that are clear from the code, as such information rapidly gets out of date. Comments that disagree with the code are of negative value. Short comments should be what comments, such as ``compute mean value'', rather than how comments such as ``sum of values divided by n''. C is not assembler; putting a comment at the top of a 3-10 line section telling what it does overall is often more useful than a comment on each line describing micrologic.

Comments should justify offensive code. The justification should be that something bad will happen if unoffensive code is used. Just making code faster is not enough to rationalize a hack; the performance must be shown to be unacceptable without the hack. The comment should explain the unacceptable behavior and describe why the hack is a ``good'' fix.

Comments that describe data structures, algorithms, etc., should be in block comment form with the opening /* in columns 1-2, a * in column 2 before each line of comment text, and the closing */ in columns 2-3.

/*
 *	Here is a block comment.
 *	The comment text should be tabbed or spaced over uniformly.
 *	The opening slash-star and closing star-slash are alone on a line.
 */

Note that grep '^. *' will catch all block comments in the file. Some automated program-analysis packages use different characters before comment lines as a marker for lines with specific items of information. In particular, a line with a `-' in a comment preceding a function is sometimes assumed to be a one-line summary of the function's purpose. Very long block comments such as drawn-out discussions and copyright notices often start with /* in columns 1-2, no leading * before lines of text, and the closing */ in columns 1-2. Block comments inside a function are appropriate, and they should be tabbed over to the same tab setting as the code that they describe. One-line comments alone on a line should be indented to the tab setting of the code that follows.

if (argc > 1) {
	/* Get input file from command line. */
	if (freopen(argv[1], "r", stdin) == NULL) {
		perror (argv[1]);
	}
}

Very short comments may appear on the same line as the code they describe, and should be tabbed over to separate them from the statements. If more than one short comment appears in a block of code they should all be tabbed to the same tab setting.

if (a == EXCEPTION) {
	b = TRUE;			/* special case */
} else {
	b = isprime(a);			/* works only for odd a */
}

Declarations

Global declarations should begin in column 1. All external data declaration should be preceded by the extern keyword. If an external variable is an array that is defined with an explicit size, then the array bounds must be repeated in the extern declaration unless the size is always encoded in the array (e.g., a read-only character array that is always null-terminated). Repeated size declarations are particularly beneficial to someone picking up code written by another.

The ``pointer'' qualifier, `*', should be with the variable name rather than with the type.

char		*s, *t, *u;

char*	s, t, u;

Unrelated declarations, even of the same type, should be on separate lines. A comment describing the role of the object being declared should be included, with the exception that a list of #defined constants do not need comments if the constant names are sufficient documentation. The names, values, and comments are usually tabbed so that they line up underneath each other. Use the tab character rather than blanks (spaces). For structure and union template declarations, each element should be alone on a line with a comment describing it. The opening brace ({) should be on the same line as the structure tag, and the closing brace (}) should be in column 1.

struct boat {
	int		wllength;	/* water line length in meters */
	int		type;		/* see below */
	long		sailarea;	/* sail area in square mm */
};

/* defines for boat.type */
#define	KETCH	(1)
#define	YAWL	(2)
#define	SLOOP	(3)
#define	SQRIG	(4)
#define	MOTOR	(5)

These defines are sometimes put right after the declaration of type, within the struct declaration, with enough tabs after the `#' to indent define one level more than the structure member declarations. When the actual values are unimportant, the enum facility is better.

enum bt { KETCH=1, YAWL, SLOOP, SQRIG, MOTOR };
struct boat {
	int		wllength;	/* water line length in meters */
	enum bt		type;		/* what kind of boat */
	long		sailarea;	/* sail area in square mm */
};

Any variable whose initial value is important should be explicitly initialized, or at the very least should be commented to indicate that C's default initialization to zero is being relied upon. The empty initializer, ``{}'', should never be used. Structure initializations should be fully parenthesized with braces. Constants used to initialize longs should be explicitly long. Use capital letters; for example two long ``2l'' looks a lot like ``21'', the number twenty-one.

int		x = 1;
char		*msg = "message";
struct boat	winner[] = {
	{ 40, YAWL, 6000000L },
	{ 28, MOTOR, 0L },
	{ 0 },
};

In any file which is part of a larger whole rather than a self-contained program, maximum use should be made of the static keyword to make functions and variables local to single files. Variables in particular should be accessible from other files only when there is a clear need that cannot be filled in another way. Such usage should be commented to make it clear that another file's variables are being used; the comment should name the other file. If your debugger hides static objects you need to see during debugging, declare them as STATIC and #define STATIC as needed.

The most important types should be highlighted by typedeffing them, even if they are only integers, as the unique name makes the program easier to read (as long as there are only a few things typedeffed to integers!). Avoid typedeffing structures and unions, as this hides the fact that an object is composite from the code reader.

The return type of functions should always be declared. Always use function prototypes. One common mistake is to omit the declaration of external math functions that return double. The compiler then assumes that the return value is an integer and the bits are dutifully converted into a (meaningless) floating point value.

``C takes the point of view that the programmer is always right.'' - Michael DeCorte

Function Declarations

Each function should be preceded by a block comment prologue that gives a short description of what the function does and (if not clear) how to use it. Discussion of non-trivial design decisions and side-effects is also appropriate. Avoid duplicating information clear from the code.

The function return type should be alone on a line, (optionally) indented one stop. ``Tabstops'' can be blanks (spaces) inserted by your editor in clumps of 2, 4, or 8. Do not default to int; if the function does not return a value then it should be given return type void. If the value returned requires a long explanation, it should be given in the prologue; otherwise it can be on the same line as the return type, tabbed over. The function name (and the formal parameter list) should be alone on a line, in column 1. Destination (return value) parameters should generally be first (on the left). All local declarations and code within the function body should be tabbed over one stop. The opening brace of the function body should be alone on a line beginning in column 1.

Each parameter should be declared (do not default to int). In general the role of each variable in the function should be described. This may either be done in the function comment or, if each declaration is on its own line, in a comment on that line. Loop counters called ``i'', string pointers called ``s'', and integral types called ``c'' and used for characters are typically excluded. If a group of functions all have a like parameter or local variable, it helps to call the repeated variable by the same name in all functions. (Conversely, avoid using the same name for different purposes in related functions.) Like parameters should also appear in the same place in the various argument lists.

Comments for parameters and local variables should be tabbed so that they line up underneath each other. Local variable declarations should be separated from the function's statements by a blank line.

Be careful when you use or declare functions that take a variable number of arguments (``varargs''). Always use the ``stdarg.h'' header definitions and do not rely on item order on the stack.

If the function uses any external variables (or functions) that are not declared globally in the file, these should have their own declarations in the function body using the extern keyword.

Avoid local declarations that override declarations at higher levels. In particular, local variables should not be redeclared in nested blocks. Although this is valid C, the potential confusion is enough that lint will complain about it when given the -h option.

Whitespace

int i;main(){for(;i["]<i;++i){--i;}"];read('-'-'-',i+++"hell\
o, world!\n",'/'/'/'));}read(j,i,p){write(j/p+p,i---j,i/i);}
- Dishonorable mention, Obfuscated C Code Contest, 1984.
Author requested anonymity.

Use vertical and horizontal whitespace generously. Indentation and spacing should reflect the block structure of the code; e.g., there should be at least 2 blank lines between the end of one function and the comments for the next.

A long string of conditional operators should be split onto separate lines.

if (foo->next==NULL && totalcount<needed && needed<=MAX_ALLOT
	&& server_active(current_input)) { ...

if (foo->next == NULL
	&& totalcount < needed && needed <= MAX_ALLOT
	&& server_active(current_input))
{
	...

for (curr = *listp, trail = listp;
	curr != NULL;
	trail = &(curr->next), curr = curr->next )
{
	...

c = (a == b)
	? d + f(a)
	: f(b) - d;

Examples

/*
 *	Determine if the sky is blue by checking that it isn't night.
 *	CAVEAT: Only sometimes right.  May return TRUE when the answer
 *	is FALSE.  Consider clouds, eclipses, short days.
 *	NOTE: Uses `hour' from `hightime.c'.  Returns `int' for
 *	compatibility with the old version.
 */
int						/* true or false */
skyblue(void)
{
	extern int	hour;		/* current hour of the day */

	return (hour >= MORNING && hour <= EVENING);
}

/*
 *	Find the last element in the linked list
 *	pointed to by nodep and return a pointer to it.
 *	Return NULL if there is no last element.
 */
node_t *
tail(node_t *nodep)
{
	node_t	*np;		/* advances to NULL */
	node_t	*lp;		/* follows one behind np */

	if (nodep == NULL)
		return (NULL);
	for (np = lp = nodep; np != NULL; lp = np, np = np->next)
		;	/* VOID */
	return (lp);
}

Simple Statements

There should be only one statement per line unless the statements are very closely related.

case FOO:	  oogle (zork);  boogle (zork);  break;
case BAR:	  oogle (bork);  boogle (zork);  break;
case BAZ:	  oogle (gork);  boogle (bork);  break;

while (*dest++ = *src++)
	;	/* VOID */

Do not default the test for non-zero, i.e.

if (f() != FAIL)

if (f())

#define STREQ(a, b) (strcmp((a), (b)) == 0)

The non-zero test is often defaulted for predicates and other functions or expressions which meet the following restrictions:

• Evaluates to 0 for false, nothing else.
• Is named so that the meaning of (say) a `true' return is absolutely obvious. Call a predicate isvalid or valid, not checkvalid.

It is common practice to declare a boolean type ``bool'' in a global include file. The special names improve readability immensely.

typedef int	bool;
#define FALSE	0
#define TRUE	1

typedef enum { NO=0, YES } bool;

Even with these declarations, do not check a boolean value for equality with 1 (TRUE, YES, etc.); instead test for inequality with 0 (FALSE, NO, etc.). Most functions are guaranteed to return 0 if false, but only non-zero if true. Thus,

if (func() == TRUE) { ...

if (func() != FALSE) { ...

if (isvalid()) { ...

There is a time and a place for embedded assignment statements. In some constructs there is no better way to accomplish the results without making the code bulkier and less readable.

while ((c = getchar()) != EOF) {
	process the character
}

a = b + c;
d = a + r;

d = (a = b + c) + r;

Goto statements should be used sparingly, as in any well-structured code. The main place where they can be usefully employed is to break out of several levels of switch, for, and while nesting, although the need to do such a thing may indicate that the inner constructs should be broken out into a separate function, with a success/failure return code.

	for (...) {
		while (...) {
			...
			if (disaster)
				goto error;
	    
		}
	}
	...
error:
	clean up the mess

Compound Statements

A compound statement is a list of statements enclosed by braces. There are many common ways of formatting the braces. Please be consistent with our local standard. When editing someone else's code, always use the style used in that code.

control {
                statement;
                statement;
}

The style above is called ``K&R style'', and is preferred if you haven't already got a favorite. With K&R style, the else part of an if-else statement and the while part of a do-while statement should appear on the same line as the close brace. With most other styles, the braces are always alone on a line.

When a block of code has several labels (unless there are a lot of them), the labels are placed on separate lines. The fall-through feature of the C switch statement, (that is, when there is no break between a code segment and the next case statement) must be commented for future maintenance. A lint-style comment/directive is best.

switch (expr) {
case ABC:
case DEF:
	statement;
	break;
case UVW:
	statement;
	/*FALLTHROUGH*/
case XYZ:
	statement;
	break;
}

Here, the last break is unnecessary, but is required because it prevents a fall-through error if another case is added later after the last one. The default case, if used, should be last and does not require a break if it is last.

Whenever an if-else statement has a compound statement for either the if or else section, the statements of both the if and else sections should both be enclosed in braces (called fully bracketed syntax).

if (expr) {
	statement;
} else {
	statement;
	statement;
}

if (ex1) {
	if (ex2) {
		funca();
	}
} else {
	funcb();
}

An if-else with else if should be written with the else conditions left-justified.

if (STREQ (reply, "yes")) {
	statements for yes
	...
} else if (STREQ (reply, "no")) {
	...
} else if (STREQ (reply, "maybe")) {
	...
} else {
	statements for default
	...
}

Do-while loops should always have braces around the body.

Forever loops should be coded using the for(;;) construct, and not the while(1) construct. Do not use braces for single statement blocks.

for (;;)
	function();

Sometimes an if causes an unconditional control transfer via break, continue, goto, or return. The else should be implicit and the code should not be indented.

if (level > limit)
	return (OVERFLOW)
normal();
return (level);

Operators

Unary operators should not be separated from their single operand. Generally, all binary operators except `.' and `->' should be separated from their operands by blanks. Some judgement is called for in the case of complex expressions, which may be clearer if the ``inner'' operators are not surrounded by spaces and the ``outer'' ones are.

If you think an expression will be hard to read, consider breaking it across lines. Splitting at the lowest-precedence operator near the break is best. Since C has some unexpected precedence rules, expressions involving mixed operators should be parenthesized. Too many parentheses, however, can make a line harder to read because humans aren't good at parenthesis-matching.

There is a time and place for the binary comma operator, but generally it should be avoided. The comma operator is most useful to provide multiple initializations or operations, as in for statements. Complex expressions, for instance those with nested ternary ?: operators, can be confusing and should be avoided if possible. There are some macros like getchar where both the ternary operator and comma operators are useful. The logical expression operand before the ?: should be parenthesized and both return values must be the same type.

Naming Conventions

Individual projects will no doubt have their own naming conventions. There are some general rules however.

• Names with leading and trailing underscores are reserved for system purposes and should not be used for any user-created names. Most systems use them for names that the user should not have to know. If you must have your own private identifiers, begin them with a letter or two identifying the package to which they belong.
• #define constants should be in all CAPS.
• Enum constants are all CAPS
• Function, typedef, and variable names, as well as struct, union, and enum tag names should be in lower case.
• Many macro ``functions'' are in all CAPS. Some macros (such as getchar and putchar) are in lower case since they may also exist as functions. Lower-case macro names are only acceptable if the macros behave like a function call, that is, they evaluate their parameters exactly once and do not assign values to named parameters. Sometimes it is impossible to write a macro that behaves like a function even though the arguments are evaluated exactly once.
• Avoid names that differ only in case, like foo and Foo. Similarly, avoid foobar and foo_bar. The potential for confusion is considerable.
• Similarly, avoid names that look like each other. On many terminals and printers, `l', `1' and `I' look quite similar. A variable named `l' is particularly bad because it looks so much like the constant `1'.

In general, global names (including enums) should have a common prefix identifying the module that they belong with. Globals may alternatively be grouped in a global structure. Typedeffed names often have ``_t'' appended to their name.

Avoid names that might conflict with various standard library names. Some systems will include more library code than you want. Also, your program may be extended someday.

Also note the following (from [15]):

``Length is not a virtue in a name; clarity of expression is. A global variable rarely used may deserve a long name, maxphysaddr say. An array index used on every line of a loop needn't be named any more elaborately than i. Saying index or elementnumber is more to type (or calls upon your text editor) and obscures the details of the computation. When the variable names are huge, it's harder to see what's going on. This is partly a typographic issue; consider

for(i=0 to 100)
        array[i]=0

vs.

for(elementnumber=0 to 100)
        array[elementnumber]=0;

The problem gets worse fast with real examples. Indices are just notation, so treat them as such.''

``Pointers also require sensible notation. np is just as mnemonic as nodepointer if you consistently use a naming convention from which np means ``node pointer'' is easily derived.''

As in all other aspects of readable programming, consistency is important in naming. If you call one variable maxphysaddr, don't call its cousin lowestaddress.''

``Finally, I prefer minimum-length but maximum-information names, and then let the context fill in the rest. Globals, for instance, typically have little context when they are used, so their names need to be relatively evocative. Thus I say maxphysaddr (not MaximumPhysicalAddress) for a global variable, but np not NodePointer for a pointer locally defined and used. This is largely a matter of taste, but taste is relevant to clarity.

I eschew embedded capital letters in names; to my prose-oriented eyes, they are too awkward to read comfortably. They jangle like bad typography.'' ``Procedure names should reflect what they do; function names should reflect what they return. Functions are used in expressions, often in things like if's, so they need to read appropriately.

if(checksize(x))

is unhelpful because we can't deduce whether checksize returns true on error or non-error; instead

if(validsize(x))

makes the point clear and makes a future mistake in using the routine less likely.''

Constants

Numerical constants should not be coded directly. The #define feature of the C preprocessor should be used to give constants meaningful names. Symbolic constants make the code easier to read. Defining the value in one place also makes it easier to administer large programs since the constant value can be changed uniformly by changing only the define. The enumeration data type is a better way to declare variables that take on only a discrete set of values, since additional type checking is often available. At the very least, any directly-coded numerical constant must have a comment explaining the derivation of the value.

Constants should be defined consistently with their use; e.g. use 540.0 for a float instead of 540 with an implicit float cast. There are some cases where the constants 0 and 1 may appear as themselves instead of as defines. For example if a for loop indexes through an array, then

for (i = 0; i < ARYBOUND; i++)

door_t *front_door = opens(door[i], 7);
if (front_door == 0)
	error("can't open %s\n", door[i]);

Simple character constants should be defined as character literals rather than numbers. Non-text characters are discouraged as non-portable. If non-text characters are necessary, particularly if they are used in strings, they should be written using a escape character of three octal digits rather than one (e.g., `\007'). Even so, such usage should be considered machine-dependent and treated as such.

Macros

Complex expressions can be used as macro parameters, and operator-precedence problems can arise unless all occurrences of parameters have parentheses around them. There is little that can be done about the problems caused by side effects in parameters except to avoid side effects in expressions (a good idea anyway) and, when possible, to write macros that evaluate their parameters exactly once. There are times when it is impossible to write macros that act exactly like functions.

Some macros also exist as functions (e.g., getc and fgetc). The macro should be used in implementing the function so that changes to the macro will be automatically reflected in the function. Care is needed when interchanging macros and functions since function parameters are passed by value, while macro parameters are passed by name substitution. Carefree use of macros requires that they be declared carefully.

Macros should avoid using globals, since the global name may be hidden by a local declaration. Macros that change named parameters (rather than the storage they point at) or may be used as the left-hand side of an assignment should mention this in their comments. Macros that take no parameters but reference variables, are long, or are aliases for function calls should be given an empty parameter list, e.g.,

#define	OFF_A()	(a_global+OFFSET)
#define	BORK()	(zork())
#define	SP3()	if (b) { int x; av = f (&x); bv += x; }

Macros save function call/return overhead, but when a macro gets long, the effect of the call/return becomes negligible, so a function should be used instead.

In some cases it is appropriate to make the compiler insure that a macro is terminated with a semicolon.

if (x==3)
    SP3();
else
    BORK();

#define SP3() \
	do { if (b) { int x; av = f (&x); bv += x; }} while (0)

#ifdef lint
	static int ZERO;
#else
#	define ZERO 0
#endif
#define STMT( stuff )		do { stuff } while (ZERO)

#define SP3() \
	STMT( if (b) { int x; av = f (&x); bv += x; } )

Except for type casts, sizeof, and hacks such as the above, macros should contain keywords only if the entire macro is surrounded by braces.

Conditional Compilation

Conditional compilation is useful for things like machine-dependencies, debugging, and for setting certain options at compile-time. Beware of conditional compilation. Various controls can easily combine in unforeseen ways. If you #ifdef machine dependencies, make sure that when no machine is specified, the result is an error, not a default machine. (Use ``#error'' and indent it so it works with older compilers.) If you #ifdef optimizations, the default should be the unoptimized code rather than an uncompilable program. Be sure to test the unoptimized code.

Note that the text inside of an #ifdeffed section may be scanned (processed) by the compiler, even if the #ifdef is false. Thus, even if the #ifdeffed part of the file never gets compiled (e.g., ),"#ifdefCOMMENT" it cannot be arbitrary text.

Put #ifdefs in header files instead of source files when possible. Use the #ifdefs to define macros that can be used uniformly in the code. For instance, a header file for checking memory allocation might look like (omitting definitions for REALLOC and FREE):

#ifdef DEBUG
	extern void *mm_malloc();
#	define MALLOC(size) (mm_malloc(size))
#else
	extern void *malloc();
#	define MALLOC(size) (malloc(size))
#endif

Conditional compilation should generally be on a feature-by-feature basis. Machine or operating system dependencies should be avoided in most cases.

#ifdef 4BSD
	long t = time ((long *)NULL);
#endif

Program Structure

The following are some excerpts from [15] relevant to program structure and organisation.

Complexity

Most programs are too complicated - that is, more complex than they need to be to solve their problems efficiently. Why? Mostly it's because of bad design, but I will skip that issue here because it's a big one. But programs are often complicated at the microscopic level, and that is something I can address here.

Rule 1. You can't tell where a program is going to spend its time. Bottlenecks occur in surprising places, so don't try to second guess and put in a speed hack until you've proven that's where the bottleneck is.

Rule 2. Measure. Don't tune for speed until you've measured, and even then don't unless one part of the code overwhelms the rest.

Rule 3. Fancy algorithms are slow when n is small, and n is usually small. Fancy algorithms have big constants. Until you know that n is frequently going to be big, don't get fancy. (Even if n does get big, use Rule 2 first.) For example, binary trees are always faster than splay trees for workaday problems.

Rule 4. Fancy algorithms are buggier than simple ones, and they're much harder to implement. Use simple algorithms as well as simple data structures.

The following data structures are a complete list for almost all practical programs:

• array
• linked list
• hash table
• binary tree

Rule 5. Data dominates. If you've chosen the right data structures and organized things well, the algorithms will almost always be self-evident. Data structures, not algorithms, are central to programming. (See Brooks p. 102.)

Rule 6. There is no Rule 6.

Programming with data.

Algorithms, or details of algorithms, can often be encoded compactly, efficiently and expressively as data rather than, say, as lots of if statements. The reason is that the complexity of the job at hand, if it is due to a combination of independent details, can be encoded. A classic example of this is parsing tables, which encode the grammar of a programming language in a form interpretable by a fixed, fairly simple piece of code. Finite state machines are particularly amenable to this form of attack, but almost any program that involves the `parsing' of some abstract sort of input into a sequence of some independent `actions' can be constructed profitably as a data-driven algorithm.

Perhaps the most intriguing aspect of this kind of design is that the tables can sometimes be generated by another program - a parser generator, in the classical case. As a more earthy example, if an operating system is driven by a set of tables that connect I/O requests to the appropriate device drivers, the system may be `configured' by a program that reads a description of the particular devices connected to the machine in question and prints the corresponding tables.

One of the reasons data-driven programs are not common, at least among beginners, is the tyranny of Pascal. Pascal, like its creator, believes firmly in the separation of code and data. It therefore (at least in its original form) has no ability to create initialized data. This flies in the face of the theories of Turing and von Neumann, which define the basic principles of the stored-program computer. Code and data are the same, or at least they can be. How else can you explain how a compiler works? (Functional languages have a similar problem with I/O.)

Function pointers

Another result of the tyranny of Pascal is that beginners don't use function pointers. (You can't have function-valued variables in Pascal.) Using function pointers to encode complexity has some interesting properties.

Some of the complexity is passed to the routine pointed to. The routine must obey some standard protocol - it's one of a set of routines invoked identically - but beyond that, what it does is its business alone. The complexity is distributed.

There is this idea of a protocol, in that all functions used similarly must behave similarly. This makes for easy documentation, testing, growth and even making the program run distributed over a network - the protocol can be encoded as remote procedure calls.

I argue that clear use of function pointers is the heart of object-oriented programming. Given a set of operations you want to perform on data, and a set of data types you want to respond to those operations, the easiest way to put the program together is with a group of function pointers for each type. This, in a nutshell, defines class and method. The O-O languages give you more of course - prettier syntax, derived types and so on - but conceptually they provide little extra.

Combining data-driven programs with function pointers leads to an astonishingly expressive way of working, a way that, in my experience, has often led to pleasant surprises. Even without a special O-O language, you can get 90% of the benefit for no extra work and be more in control of the result. I cannot recommend an implementation style more highly. All the programs I have organized this way have survived comfortably after much development - far better than with less disciplined approaches. Maybe that's it: the discipline it forces pays off handsomely in the long run.

Debugging

``C Code. C code run. Run, code, run... PLEASE!!!'' - Barbara Tongue

If you use enums, the first enum constant should have a non-zero value, or the first constant should indicate an error.

enum { STATE_ERR, STATE_START, STATE_NORMAL, STATE_END } state_t;
enum { VAL_NEW=1, VAL_NORMAL, VAL_DYING, VAL_DEAD } value_t;

Check for error return values, even from functions that ``can't'' fail. Consider that close() and fclose() can and do fail, even when all prior file operations have succeeded. Write your own functions so that they test for errors and return error values or abort the program in a well-defined way. Include a lot of debugging and error-checking code and leave most of it in the finished product. Check even for ``impossible'' errors. [8]

Use the assert facility to insist that each function is being passed well-defined values, and that intermediate results are well-formed.

Build in the debug code using as few #ifdefs as possible. For instance, if ``mm_malloc'' is a debugging memory allocator, then MALLOC will select the appropriate allocator, avoids littering the code with #ifdefs, and makes clear the difference between allocation calls being debugged and extra memory that is allocated only during debugging.

#ifdef DEBUG
#	define MALLOC(size)  (mm_malloc(size))
#else
#	define MALLOC(size)  (malloc(size))
#endif

Check bounds even on things that ``can't'' overflow. A function that writes on to variable-sized storage should take an argument maxsize that is the size of the destination. If there are times when the size of the destination is unknown, some `magic' value of maxsize should mean ``no bounds checks''. When bound checks fail, make sure that the function does something useful such as abort or return an error status.

/*
 * INPUT: A null-terminated source string `src' to copy from and
 * a `dest' string to copy to.  `maxsize' is the size of `dest'
 * or UINT_MAX if the size is not known.  `src' and `dest' must
 * both be shorter than UINT_MAX, and `src' must be no longer than
 * `dest'.
 * OUTPUT: The address of `dest' or NULL if the copy fails.
 * `dest' is modified even when the copy fails.
 */
char *
copy (char *dest, size_t maxsize, char *src)
{
	char *dp = dest;

	while (maxsize-- > 0)
		if ((*dp++ = *src++) == '\0')
			return (dest);

	return (NULL);
}

In all, remember that a program that produces wrong answers twice as fast is infinitely slower. The same is true of programs that crash occasionally or clobber valid data.

Portability

``C combines the power of assembler with the portability of assembler.''
- Anonymous, alluding to Bill Thacker.

The advantages of portable code are well known. This section gives some guidelines for writing portable code. Here, ``portable'' means that a source file can be compiled and executed on different machines with the only change being the inclusion of possibly different header files and the use of different compiler flags. The header files will contain #defines and typedefs that may vary from machine to machine. In general, a new ``machine'' is different hardware, a different operating system, a different compiler, or any combination of these. Reference [1] contains useful information on both style and portability. The following is a list of pitfalls to be avoided and recommendations to be considered when designing portable code:

• Write portable code first, worry about detail optimizations only on machines where they prove necessary. Optimized code is often obscure. Optimizations for one machine may produce worse code on another. Document performance hacks and localize them as much as possible. Documentation should explain how it works and why it was needed (e.g., ``loop executes 6 zillion times'').
• Recognize that some things are inherently non-portable. Examples are code to deal with particular hardware registers such as the program status word, and code that is designed to support a particular piece of hardware, such as an assembler or I/O driver. Even in these cases there are many routines and data organizations that can be made machine independent.
• Organize source files so that the machine-independent code and the machine-dependent code are in separate files. Then if the program is to be moved to a new machine, it is a much easier task to determine what needs to be changed. Comment the machine dependence in the headers of the appropriate files.
• Any behavior that is described as ``implementation defined'' should be treated as a machine (compiler) dependency. Assume that the compiler or hardware does it some completely screwy way.
• Pay attention to word sizes. Objects may be non-intuitive sizes, Pointers are not always the same size as ints, the same size as each other, or freely interconvertible. The following table shows bit sizes for basic types in C for various machines and compilers.

  type	pdp11	VAX/11	68000	Cray-2	Unisys	Harris	80386-Pentium
  	series		family		1100	H800
  char	8	8	8	8	9	8	8
  short	16	16	8/16	64(32)	18	24	8/16
  int	16	32	16/32	64(32)	36	24	16/32
  long	32	32	32	64	36	48	32
  char*	16	32	32	64	72	24	16/32/48
  int*	16	32	32	64(24)	72	24	16/32/48
  int(*)()	16	32	32	64	576	24	16/32/48

  Some machines have more than one possible size for a given type. The size you get can depend both on the compiler and on various compile-time flags. The following table shows ``safe'' type sizes on the majority of systems. Unsigned numbers are the same bit size as signed numbers.

  Type	Minimum	No Smaller
  	# Bits	Than
  char	8
  short	16	char
  int	16	short
  long	32	int
  float	24
  double	38	float
  any *	14
  char *	15	any *
  void *	15	any *

• The void* type is guaranteed to have enough bits of precision to hold a pointer to any data object. The void(*)() type is guaranteed to be able to hold a pointer to any function. Use these types when you need a generic pointer. Be sure to cast pointers back to the correct type before using them.
• Even when, say, an int* and a char* are the same size, they may have different formats. For example, the following will fail on some machines that have sizeof(int*) equal to sizeof(char*). The code fails because free expects a char* and gets passed an int*.

  int *p = (int *) malloc (sizeof(int));
  free (p);
  

• Note that the size of an object does not guarantee the precision of that object. The Cray-2 may use 64 bits to store an int, but a long cast into an int and back to a long may be truncated to 32 bits.
• The integer constant zero may be cast to any pointer type. The resulting pointer is called a null pointer for that type, and is different from any other pointer of that type. A null pointer always compares equal to the constant zero. A null pointer might not compare equal with a variable that has the value zero. Null pointers are not always stored with all bits zero. Null pointers for two different types are sometimes different. A null pointer of one type cast in to a pointer of another type will be cast in to the null pointer for that second type.
• On ANSI compilers, when two pointers of the same type access the same storage, they will compare as equal. When non-zero integer constants are cast to pointer types, they may become identical to other pointers. On non-ANSI compilers, pointers that access the same storage may compare as different. The following two pointers, for instance, may or may not compare equal, and they may or may not access the same storage. The code may also fail to compile, fault on pointer creation, fault on pointer comparison, or fault on pointer dereferences.

  ((int *) 2 )
  ((int *) 3 )
  

  If you need `magic' pointers other than NULL, either allocate some storage or treat the pointer as a machine dependence.

  extern int x_int_dummy;		/* in x.c */
  #define X_FAIL	(NULL)
  #define X_BUSY	(&x_int_dummy)
  

  #define X_FAIL	(NULL)
  #define X_BUSY	MD_PTR1		/* MD_PTR1 from "machdep.h" */
  

• Floating-point numbers have both a precision and a range. These are independent of the size of the object. Thus, overflow (underflow) for a 32-bit floating-point number will happen at different values on different machines. Also, 4.9 times 5.1 will yield two different numbers on two different machines. Differences in rounding and truncation can give surprisingly different answers.
• On some machines, a double may have less range or precision than a float.
• On some machines the first half of a double may be a float with similar value. Do not depend on this.
• Watch out for signed characters. On Intel architectures and some VAXes, for instance, characters are sign extended when used in expressions, which is not the case on many other machines. Code that assumes signed/unsigned is unportable. For example, array[c] won't work if c is supposed to be positive and is instead signed and negative. If you must assume signed or unsigned characters, comment them as SIGNED or UNSIGNED. Unsigned behavior can be guaranteed with unsigned char Be particularly careful if your program will deal with above-127 character values (e.g. to use strings containing Greek characters). Also note that some compilers (e.g. Watcom C 9.1) produce wrong results when strings containing above-127 characters are passed to the strcmp function.
• Avoid assuming ASCII or a particular character set (ELOT, 437). (Use "<ctype.h>" where possible, but beware that their behavior varies considerably between C implementations. For instance, if c is not an upper-case letter, tolower(c) may return c or garbage.) If Greek strings will be processed use the system-provided ctype.h may not work correctly. If you must assume, document and localize. Remember that characters may hold (much) more than 8 bits.
• Code that takes advantage of the two's complement representation of numbers on most machines should not be used. Optimizations that replace arithmetic operations with equivalent shifting operations are particularly suspect. If absolutely necessary, machine-dependent code should be #ifdeffed or operations should be performed by #ifdeffed macros. You should weigh the time savings with the potential for obscure and difficult bugs when your code is moved.
• In general, if the word size or value range is important, typedef ``sized'' types. Large programs should have a central header file which supplies typedefs for commonly-used width-sensitive types, to make it easier to change them and to aid in finding width-sensitive code. Unsigned types other than "unsignedint" are highly compiler-dependent. If a simple loop counter is being used where either 16 or 32 bits will do, then use int, since it will get the most efficient (natural) unit for the current machine.
• Data alignment is also important. For instance, on various machines a 4-byte integer may start at any address, start only at an even address, or start only at a multiple-of-four address. Thus, a particular structure may have its elements at different offsets on different machines, even when given elements are the same size on all machines. Indeed, a structure of a 32-bit pointer and an 8-bit character may be 3 sizes on 3 different machines. As a corollary, pointers to objects may not be interchanged freely; saving an integer through a pointer to 4 bytes starting at an odd address will sometimes work, sometimes cause a core dump, and sometimes fail silently (clobbering other data in the process). Pointer-to-character is a particular trouble spot on machines which do not address to the byte. Alignment considerations and loader peculiarities make it very rash to assume that two consecutively-declared variables are together in memory, or that a variable of one type is aligned appropriately to be used as another type.
• The bytes of a word are of increasing significance with increasing address on machines such as the Intel x88 and the VAX (little-endian) and of decreasing significance with increasing address on other machines such as the 68000 (big-endian). The order of bytes in a word and of words in larger objects (say, a double word) might not be the same. Hence any code that depends on the left-right orientation of bits in an object deserves special scrutiny. Bit fields within structure members will only be portable so long as two separate fields are never concatenated and treated as a unit. [1,3] Actually, it is nonportable to concatenate any two variables.
• There may be unused holes in structures. Suspect unions used for type cheating. Specifically, a value should not be stored as one type and retrieved as another. An explicit tag field for unions may be useful.
• Different compilers use different conventions for returning structures. This causes a problem when libraries return structure values to code compiled with a different compiler. Structure pointers are not a problem unless you have specified an non-default structure packing option to your compiler.
• Do not make assumptions about the parameter passing mechanism. especially pointer sizes and parameter evaluation order, size, etc. The following code, for instance, is very nonportable.

  	c = foo (getchar(), getchar());
  
  char
  foo (char c1, char c2, char c3)
  {
  	char bar = *(&c1 + 1);
  	return (bar);			/* often won't return c2 */
  }
  

  This example has lots of problems. The stack may grow up or down (indeed, there need not even be a stack!). Parameters may be widened when they are passed, so a char might be passed as an int, for instance. Arguments may be pushed left-to-right, right-to-left, in arbitrary order, or passed in registers (not pushed at all). The order of evaluation may differ from the order in which they are pushed. One compiler may use several (incompatible) calling conventions.
• On some machines, the null character pointer "((char*)0)" is treated the same way as a pointer to a null string. Do not depend on this.
• Do not modify string constants. Some libraries attempt to modify and then restore read-only string variables. Programs sometimes won't port because of these broken libraries. The libraries are getting better. One particularly notorious (bad) example is

  s = "/dev/tty??";
  strcpy (&s[8], ttychars);
  

• The address space may have holes. Simply computing the address of an unallocated element in an array (before or after the actual storage of the array) may crash the program. If the address is used in a comparison, sometimes the program will run but clobber data, give wrong answers, or loop forever. In ANSI C, a pointer into an array of objects may legally point to the first element after the end of the array; this is usually safe in older implementations. This ``outside'' pointer may not be dereferenced.
• Only the == and != comparisons are defined for all pointers of a given type. It is only portable to use <, <=, >, or >= to compare pointers when they both point in to (or to the first element after) the same array. It is likewise only portable to use arithmetic operators on pointers that both point into the same array or the first element afterwards.
• Word size also affects shifts and masks. The following code will clear only the three rightmost bits of an int on some 68000s. On other machines it will also clear the upper two bytes.

  x &= 0177770
  

  Use instead

  x &= ~07
  

  which works properly on all machines. Bitfields do not have these problems.
• Side effects within expressions can result in code whose semantics are compiler-dependent, since C's order of evaluation is explicitly undefined in most places. Notorious examples include the following.

  a[i] = b[i++];
  

  In the above example, we know only that the subscript into b has not been incremented. The index into a could be the value of i either before or after the increment.

  struct bar_t { struct bar_t *next; } bar;
  bar->next = bar = tmp;
  

  In the second example, the address of ``bar->next'' may be computed before the value is assigned to ``bar''.

  bar = bar->next = tmp;
  

  In the third example, bar can be assigned before bar->next. Although this appears to violate the rule that ``assignment proceeds right-to-left'', it is a legal interpretation. Consider the following example:

  long i;
  short a[N];
  i = old
  i = a[i] = new;
  

  The value that ``i'' is assigned must be a value that is typed as if assignment proceeded right-to-left. However, ``i'' may be assigned the value ``(long)(short)new'' before ``a[i]'' is assigned to. Compilers do differ.
• Be suspicious of numeric values appearing in the code (``magic numbers'').
• Become familiar with existing library functions and defines. (But not too familiar. The internal details of library facilities, as opposed to their external interfaces, are subject to change without warning. They are also often quite unportable.) You should not be writing your own string compare routine, terminal control routines, or making your own defines for system structures. ``Rolling your own'' wastes your time and makes your code less readable, because another reader has to figure out whether you're doing something special in that reimplemented stuff to justify its existence. It also prevents your program from taking advantage of any microcode assists or other means of improving performance of system routines. Furthermore, it's a fruitful source of bugs. If possible, be aware of the differences between the common libraries (such as ANSI, POSIX, and so on).
• Always run your compiler with the switches set for maximum warnings. As an example run the Microsoft compilers with -W3. On Unix systems use alint.
• Suspect labels inside blocks with the associated switch or goto outside the block.
• Use explicit casts when doing arithmetic that mixes signed and unsigned values.
• The inter-procedural goto, longjmp, should be used with caution. Many implementations ``forget'' to restore values in registers. Declare critical values as volatile if you can or comment them as VOLATILE.
• Some linkers convert names to lower-case and some only recognize the first six letters as unique. Programs may break quietly on these systems.
• Beware of compiler extensions. If used, document and consider them as machine dependencies.
• A program cannot generally execute code in the data segment or write into the code segment. Even when it can, there is no guarantee that it can do so reliably.

ANSI C

Modern C compilers support the ANSI standard C [16]. Write code to run under standard C, and use features such as function prototypes, constant storage, and volatile storage. Standard C improves program performance by giving better information to optimizers. Standard C improves portability by insuring that all compilers accept the same input language and by providing mechanisms that try to hide machine dependencies or emit warnings about code that may be machine-dependent.

Formatting

Note that under ANSI C, the `#' for a preprocessor directive must be the first non-whitespace character on a line. Use this feature to improve the formatting of your files.

An ``#ifdef NAME'' should end with either ``#endif'' or ``#endif /* NAME */'', not with ``#endif NAME''. The comment should not be used on short #ifdefs, as it is clear from the code.

ANSI trigraphs may cause programs with strings containing ``??'' may break mysteriously.

The style for ANSI C is the same as for regular C, with two notable exceptions: storage qualifiers and parameter lists.

Because const and volatile have strange binding rules, each const or volatile object should have a separate declaration.

int const *s;		/* YES */
int const *s, *t;	/* NO */

Prototyped functions merge parameter declaration and definition in to one list. Parameters should be commented in the function comment.

/*
 * `bp': boat trying to get in.
 * `stall': a list of stalls, never NULL.
 * returns stall number, 0 => no room.
 */
int
enter_pier (boat_t const *bp, stall_t *stall)
{
	...

Pragmas

Pragmas are used to introduce machine-dependent code in a controlled way. Obviously, pragmas should be treated as machine dependencies. Unfortunately, the syntax of ANSI pragmas makes it impossible to isolate them in machine-dependent headers.

Pragmas are of two classes. Optimizations may safely be ignored. Pragmas that change the system behavior (``required pragmas'') may not. Required pragmas should be #ifdeffed so that compilation will abort if no pragma is selected.

Two compilers may use a given pragma in two very different ways. For instance, one compiler may use ``haggis'' to signal an optimization. Another might use it to indicate that a given statement, if reached, should terminate the program. Thus, when pragmas are used, they must always be enclosed in machine-dependent #ifdefs. Pragmas must always be #ifdefed out for non-ANSI compilers. Be sure to indent the `#' character on the #pragma, as older preprocessors will halt on it otherwise.

#if defined(__STDC__) && defined(USE_HAGGIS_PRAGMA)
	#pragma (HAGGIS)
#endif

``The `#pragma' command is specified in the ANSI standard to have an arbitrary implementation-defined effect. In the GNU C preprocessor, `#pragma' first attempts to run the game `rogue'; if that fails, it tries to run the game `hack'; if that fails, it tries to run GNU Emacs displaying the Tower of Hanoi; if that fails, it reports a fatal error. In any case, preprocessing does not continue.''
- Manual for the GNU C preprocessor for GNU CC 1.34.

Special Considerations

This section contains some miscellaneous do's and don'ts.

• Don't change syntax via macro substitution. It makes the program unintelligible to all but the perpetrator.
• Don't use floating-point variables where discrete values are needed. Using a float for a loop counter is a great way to shoot yourself in the foot. Always test floating-point numbers as <= or >=, never use an exact comparison (== or !=).
• Compilers have bugs. Common trouble spots include structure assignment and bitfields. You cannot generally predict which bugs a compiler has. You could write a program that avoids all constructs that are known broken on all compilers. You won't be able to write anything useful, you might still encounter bugs, and the compiler might get fixed in the meanwhile. Thus, you should write ``around'' compiler bugs only when you are forced to use a particular buggy compiler.
• Do not rely on automatic beautifiers. The main person who benefits from good program style is the programmer him/herself, and especially in the early design of handwritten algorithms or pseudo-code. Automatic beautifiers can only be applied to complete, syntactically correct programs and hence are not available when the need for attention to white space and indentation is greatest. Programmers can do a better job of making clear the complete visual layout of a function or file, with the normal attention to detail of a careful programmer. (In other words, some of the visual layout is dictated by intent rather than syntax and beautifiers cannot read minds.) Sloppy programmers should learn to be careful programmers instead of relying on a beautifier to make their code readable.
• Accidental omission of the second ``='' of the logical compare is a problem. Use explicit tests. Avoid assignment with implicit test.

  abool = bbool;
  if (abool) { ...
  

  When embedded assignment is used, make the test explicit so that it doesn't get ``fixed'' later.

  while ((abool = bbool) != FALSE) { ...
  

  while (abool = bbool) { ...	/* VALUSED */
  

  while (abool = bbool, abool) { ...
  

• Explicitly comment variables that are changed out of the normal control flow, or other code that is likely to break during maintenance.
• Modern compilers will put variables in registers automatically. Do not use the register keyword.

Make

One very useful tool is make [7]. During development, make recompiles only those modules that have been changed since the last time make was used. It can be used to automate other tasks, as well. Some common conventions include:

all

always makes all binaries

clean

remove all intermediate files

debug

make a test binary 'a.out' or 'debug'

depend

make transitive dependencies

install

install binaries, libraries, etc.

deinstall

back out of ``install''

print/list

make a hard copy of all source files

shar

make a shar of all source files

spotless

make clean, use revision control to put away sources. Note: doesn't remove Makefile, although it is a source file

source

undo what spotless did

tags

run ctags, (using the -t flag is suggested)

rdist

distribute sources to other hosts

zip

create a zip file for distribution file.c

check out the named file from revision control

Project-Dependent Standards

Individual projects may wish to establish additional standards beyond those given here. The following issues are some of those that should be addressed by each project program administration group.

• What additional naming conventions should be followed? In particular, systematic prefix conventions for functional grouping of global data and also for structure or union member names can be useful.
• What kind of include file organization is appropriate for the project's particular data hierarchy?
• What procedures should be established for reviewing compiler warnings? A tolerance level needs to be established in concert with the compiler options to prevent unimportant complaints from hiding complaints about real bugs or inconsistencies.
• What kind of revision control needs to be used?

Conclusion

A set of standards has been presented for C programming style. Among the most important points are:

• The proper use of white space and comments so that the structure of the program is evident from the layout of the code. The use of simple expressions, statements, and functions so that they may be understood easily.
• To keep in mind that you or someone else will likely be asked to modify code or make it run on a different machine sometime in the future. Craft code so that it is portable to obscure machines. Localize optimizations since they are often confusing and may be ``pessimizations'' on other machines.
• Many style choices are arbitrary. Having a style that is consistent (particularly with group standards) is more important than following absolute style rules. Mixing styles is worse than using any single bad style.

As with any standard, it must be followed if it is to be useful. If you have trouble following any of these standards don't just ignore them. Talk with an experienced programmer.

References

1. B.A. Tague, C Language Portability, Sept 22, 1977. This document issued by department 8234 contains three memos by R.C. Haight, A.L. Glasser, and T.L. Lyon dealing with style and portability.
2. S.C. Johnson, Lint, a C Program Checker, USENIX Unix Supplementary Documents, November 1986.
3. R.W. Mitze, The 3B/PDP-11 Swabbing Problem, Memorandum for File, 1273-770907.01MF, September 14, 1977.
4. R.A. Elliott and D.C. Pfeffer, 3B Processor Common Diagnostic Standards- Version 1, Memorandum for File, 5514-780330.01MF, March 30, 1978.
5. R.W. Mitze, An Overview of C Compilation of Unix User Processes on the 3B, Memorandum for File, 5521-780329.02MF, March 29, 1978.
6. B.W. Kernighan and D.M. Ritchie, The C Programming Language, Prentice Hall 1978, Second Ed. 1988, ISBN 0-13-110362-8.
7. S.I. Feldman, Make - A Program for Maintaining Computer Programs, USENIX Unix Supplementary Documents, November 1986.
8. Ian Darwin and Geoff Collyer, Can't Happen or /* NOTREACHED */ or Real Programs Dump Core, USENIX Association Winter Conference, Dallas 1985 Proceedings.
9. Brian W. Kernighan and P. J. Plauger The Elements of Programming Style. McGraw-Hill, 1974, Second Ed. 1978, ISBN 0-07-034-207-5.
10. J. E. Lapin Portable C and UNIX System Programming, Prentice Hall 1987, ISBN 0-13-686494-5.
11. Ian F. Darwin, Checking C Programs with lint, O'Reilly & Associates, 1989. ISBN 0-937175-30-7.
12. Andrew R. Koenig, C Traps and Pitfalls, Addison-Wesley, 1989. ISBN 0-201-17928-8.
13. Samuel P. Harbison and Guy L. Steele Jr. C: A Reference Manual 1984, 1987 ISBN is 0-13-109802-0
14. Mark Horton Portable C Software Prentice-Hall, Englewood Cliffs NJ 1990 ISBN is 0-13-868050-7
15. Rob Pike Notes on Programming in C
16. American National Standard for Information Systems - Programming Language - C: ANSI X3.159-1989, December, 1989. Published by the American National Standards Institute, 1430 Broadway, New York, New York 10018.

Contents