B669: Personalized Data Mining and Mapping
Identifiers and Comments

 

Here's a somewhat longer illustration of the same idea discussed in the Keypuncher's Assumption; it's the declaration part of a chat client:

public class RMIChatClient extends Applet
	implements ActionListener, ItemListener {

	static int users = 0; /* Number of users */
	TextArea chatArea; /* Messages of chat clients are displayed here */
	TextField chatInput; /* Type message here to send to everyone else */
	TextField userName; /* Enter nickname in this field */
	Button send; /* Click on this button to send your message to others in chat */
	Button closeChat; /* Button for closing your chat session */
	Panel p1; /* Panel for chatArea */
	Panel p2; /* Panel for the buttons */
	RMICollaboratorImpl collab; /* Collaborator object for
	this client */
	String name; /* Nickname of chat client */
	String host; /* Host name of chat server */
	String mname; /* Name of chat server */
	Dialog d; /* Dialog box for entering client's nickname */
	String selectedRoom = "General";
		/* Current chat room selected by the *chat client */
	List chatRooms; /* List of chat rooms */
	...
Here is the same code with more meaningful names, cleaned up comments, and better layout to let the eye more easily see relations between variables, and between variables and comments.
public class RMIChatClient extends Applet
	implements ActionListener, ItemListener
	{
	//number of chat clients presently known to be online
	private static int numberOfChatClients = 0;

	//this chat client's nickname and remote collaborator
	private String chatClientNickname;
	private RMICollaboratorImpl chatClientRMICollaborator;

	//this chat client's server's name and hostname
	private String chatServerName;
	private String chatServerHostname;

	//this chat client's chat room and the set of all chat rooms
	private String selectedChatRoom = "General";
	private List listOfChatRooms;

	//widgets to capture this chat client's outgoing chat messages
	//and to display incoming chat messages
	private TextField outgoingChatTextField;
	private TextArea incomingChatTextArea;
	private Panel chatAreaPanel;

	//control widgets
	private Button sendChatMessageButton;
	private Button closeChatSessionButton;
	private Panel buttonAreaPanel;

	//information widgets
	private TextField nicknameTextField;
	private Dialog nicknameDialogBox;
	...

Note that it's better to use //'s for in-line comments since they terminate automatically at the end of the line, whereas /*'s can keep eating a bunch of code if you make a mistake with its closure. Also, note that all the variables have been made private (I'll explain why in another Penny.)

The first rule of being a good programmer---not someone who can grind out a lot of code quickly, but someone who creates beauteous code that can live on for a long time---is to always assume that you're a complete idiot. Also assume that your readers are complete idiots, too. (Especially if that reader is me.)

Once you know that you're inevitably going to forget stuff, make mistakes, and generally goof, you will know enough to make it easy on yourself by programming as defensively as possible right from the very start.