Course Project Tips
In reviewing the drafts for the course projects, I've noticed quite a few problems that are common to many of the projects. Of course, that's the whole point of having a two-step submission process -- to give you the opportunity to get feedback (constructive, I hope) and make changes. I've jotted down a few tips to help you as you revise:
Paper
- Remember your audience -- You don't need to state what a context-free grammar is, or how one is used. You should talk about how CFG's relate to your thesis/code (e.g, giving the grammar in BNF form). You also don't need to define syntax or semantics, or tell me that planning is a difficult problem in general.
- Depth, not breadth -- This is a paper of depth, not breadth, so you don't to want to briefly mention many topics. For every sentence you should ask: Is it clear how this directly relates to the thesis of my paper? If it's not, the sentence probably shouldn't be there (or anywhere in your paper for that matter).
- More citations! -- Many people have lots of sources listed in the bibliogrpahy, but there are no sources cited in the text. Despite the lack of citations, many of the papers mention ideas from elsewhere, sans citation. I don't think that people are trying to hide the origin of the ideas; they just forget to include a citation to the original source. There's really no rule of them, but you shouldnt be surprised if you wind up with a half-dozen citations on every page.
- Copyediting -- Many of the papers have lots of spelling and grammatical mistakes, which I've tried to highlight for correction. I have a feeling many of the papers did not enjoy careful editing at the rough draft stage, but I will be more of a stickler at the final draft stage. (I didn't deduct points for any of these problems, because it is a rough draft.) clarity of your writing (including spelling and grammar) is just one factor among many, but the best idea is worth nothing if it can't be communicated to others. By the way, if you don't know the difference between that and which, you should look it up.
- Length -- For projects with minimal code, you need 8-10 pages (single-spaced, including figures and bibliography) per person. Of course, if you wish to focus on the code (and develop more than the minimum 200 lines per person), you can submit a shorter paper but you still need to discuss the code.
- Tone -- This is a research paper, so humorous anecdotes, personal observations on life and pleas for mercy are best left unwritten.
Code
- Global variables are evil -- Many people use setf to set variable values at the top level, and then modify those variables throughout the rest of the program. Bad. Very bad. Pass those values around as arguments.
- Functional programming -- This is a closely related problem to the first problem (global variables). Many people have written code that sets variable values, instead of passing data as arguments to functions and then using the returned values. You know you'e got this problem is you have lots of calls to setf or progn inside your functions. (You have the first problem if your setf's are outside of any function.)
- Nested functions -- Many people have been nesting function definitions inside one another, a clear Scheme-ism (example). The goal of trying to hide messy utility functions is laudable, but unfortunately Lisp is a bit uglier than Scheme when it comes to syntax. Most of the time, people don't worry about this problem in Lisp (i.e., they always use defun), but if you want to fix it, you can use either labels, or flet in Lisp.
- Structures -- Few people are using structures in their code, and so they have lots of "minor" variables that are part of a larger conceptual entity. For example, in a natural language program a word has a part of speech, several meanings, sometimes gender and number and so on. This is a good place to create a word strucure, and use it. We talked about structures (and arrays) last quarter, so perhaps people have forgotten the option.
- Length of code -- I've thrown out the guideline of 200 lines per person before, but I have always been reluctant to give a number. The problem is that often you need to write lines not directly related to the problem, but instead to support code. For example, for those doing natural language projects, having 100 lines that define the grammar and lexicon doesn't count as 100 lines. If you find yourself doing lots of copying and pasting, your probably not writing "countable code".
In Lisp, people write functions that look like:
(defun big-important-function (arg1 arg2)
; Does something really important
:
(defun insignificant-function (arg1)
:
)
)
If you do this in Scheme (using define), then the insignificant function is only visible in the big, important function. However, in Lisp defun always places the function name in the top-level namespace. (Return to tips)