Raft Project 2 Review/Discussion (Winter 2024)

Click here for .cc file containing examples.

Everyone made improvements from Project 1.

  • Deeper classes (simpler APIs, less specialization & information leakage)
    • Network communication pretty good in every project
  • Better error detection and logging (but still more work to do)
  • My code reviews focused more on lower-level issues (e.g. structure within classes)

Persistent Storage

  • Two challenges:
    • Log is different from other persistent state; hard to find one API for both
    • Hard to find APIs that are both general-purpose and easy-to-use for the Raft server

Class Design: Together vs. Apart

Given various pieces of functionality, which belong together in the same class/method and which should be separated in different classes/methods?

Key considerations:

  • Separate general-purpose and special-purpose code
    • Over-specialization creates information leakage and entanglement
  • Combine things that are related, separate things that are not related
    • Do one thing at a time
    • Do the whole job in one place

Examples:

  • Raft server contains state machine for shell?
  • Client main program also has code to communicate with Raft cluster?
  • One communication library for both server-server and client-server communication
  • Raft server also manages communication with clients?
  • Log class also manages other persistent state such as term and vote?
  • Separate code for sending heartbeats and AppendEntries requests (no log entries in heartbeats)?
  • Single method handles transitions to all states?

Odds and Ends

Symmetric vs. asymmetric RPC calls:

  • Symmetric: same interface for clients and servers
    • sendMessage and receiveMessage methods
  • Asymmetric: different interfaces for clients and servers
    • sendRequest and sendReply methods
    • receiveRequest and receiveReply methods

Condition variable names:

  • Name a CV after that event that causes it to be notified

Long lines are awkward:

  • With "normal" window size, code is harder to read
  • Expand window width? Wastes a lot of screen space

Should interface comments for methods go in the header file or the code file?

  • Header file (most people): since the header file defines the interface, comments should go there as well
  • Code file (my preference):
    • Having comments nearer the code increases likelihood that they will be kept up to date as code evolves
    • For someone reading the code, it's nice to have the comments next to the code (less likely to consult comments if they are in a different file)
    • For some who wants to invoke a class without reading the code file, use a document generator like Doxygen or JavaDoc to generate Web pages from comments (generators will find comments in either place)
    • Without method interface comments, the header file provides a nice "at a glance" summary of all the methods in the class.

Project 3

Get started!

Look for ways to decompose (this is a smaller project, so opportunities won't be as obvious

Risk having slightly shallow classes.

Watch out for information leakage!